UQLAB USER MANUAL

THE INPUT MODULE

C. Lataniotis, E. Torre, S. Marelli, B. Sudret

CHAIR OF RISK, SAFETY AND UNCERTAINTY QUANTIFICATION

STEFANO-FRANSCINI-PLATZ 5

CH-8093 Z

URICH

Risk, Safety &

Uncertainty Quantification

How to cite UQLAB

S. Marelli, and B. Sudret, UQLab: A framework for uncertainty quantiﬁcation in Matlab, Proc. 2nd Int. Conf. on

Vulnerability, Risk Analysis and Management (ICVRAM2014), Liverpool, United Kingdom, 2014, 2554-2563.

How to cite this manual

C. Lataniotis, E. Torre, S. Marelli, B. Sudret, UQLab user manual – The Input module, Report # UQLab-V1.3-102,

Chair of Risk, Safety and Uncertainty Quantiﬁcation, ETH Zurich, Switzerland, 2019

BIBT

X entry

@TechReport{UQdoc_13_102,

author = {Lataniotis, C. and Torre, E. and Marelli, S. and Sudret, B.},

title = {{UQLab user manual -- The Input module}},

institution = {Chair of Risk, Safety and Uncertainty Quantification, ETH Zurich,

Switzerland},

year = {2019},

note = {Report \# UQLab-V1.3-102}

}

Document Data Sheet

Document Ref. UQLAB-V1.3-102

Title: UQLAB user manual – The Input module

Authors: C. Lataniotis, E. Torre, S. Marelli, B. Sudret

Chair of Risk, Safety and Uncertainty Quantiﬁcation, ETH Zurich,

Switzerland

Date: 19/09/2019

Doc. Version Date Comments

V1.3 19/09/2019 UQLAB V1.3 release

• Added C- and D- vine copulas

• Multiple copulas through block-independence

• Added support for Rosenblatt transform

V1.2 22/02/2019 UQLAB V1.2 release

V1.1 05/07/2018 UQLAB V1.1 release

• New section in the reference list about uq subsample

V1.0 01/05/2017 UQLAB V1.0 release

• New distributions: triangular, logistic, Laplace

• Updated custom distributions section

• Updated description of several functions

V0.9 01/07/2015 Initial release

Abstract

The UQLAB INPUT module is used to deﬁne the probabilistic input model in uncertainty

quantiﬁcation problems. It offers extensive possibilities to perform operations like drawing

samples of random vectors, or transforming samples of random vectors to samples of dif-

ferent random vectors (isoprobabilistic transforms). The dependence structure between the

components of random vectors is speciﬁed with the copula formalism.

This user manual includes a review of the methods that are used to deﬁne, draw and trans-

form samples of random vectors. It also contains information about each of the available

probability distributions that can be used in the current version of UQLAB. After introducing

the theoretical aspects, an in-depth example-driven user guide is provided to help new users

to properly set up and use the INPUT module objects. Finally, a comprehensive reference list

of the methods and functions available in the UQLAB INPUT module is given at the end of the

manual.

Keywords: Probabilistic Input Model, Marginals, Copula, Isoprobabilistic Transforms, Sam-

pling

Contents

1 Theory 1

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Representation of univariate distributions . . . . . . . . . . . . . . . . . . . . 1

1.2.1 Parametric distributions . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.2 Kernel density estimates . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.3 Truncated distributions . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.4 Marginals inferred from data . . . . . . . . . . . . . . . . . . . . . . . 2

1.3 Representation of dependencies through copulas . . . . . . . . . . . . . . . . 3

1.3.1 Sklar’s transformations for densities and conditional distributions . . . 3

1.3.2 Some properties of copulas . . . . . . . . . . . . . . . . . . . . . . . . 4

1.4 Copulas currently available in UQLAB . . . . . . . . . . . . . . . . . . . . . . 4

1.4.1 Independent copula . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.4.2 Gaussian Copula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4.3 Pair copulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4.4 Vine copulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4.5 Copulas inferred from data . . . . . . . . . . . . . . . . . . . . . . . . 10

1.5 Sampling random vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.5.1 Independence copula: probability integral transform . . . . . . . . . . 10

1.5.2 Gaussian copula: Nataf transform . . . . . . . . . . . . . . . . . . . . . 11

1.5.3 Other copulas: Rosenblatt transform . . . . . . . . . . . . . . . . . . . 12

2 Usage 13

2.1 Deﬁning an INPUT object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.1.1 Deﬁning the input marginals . . . . . . . . . . . . . . . . . . . . . . . 13

2.1.2 Deﬁning the input copula . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.1.3 Independent subgroups of random variables . . . . . . . . . . . . . . . 19

2.1.4 Deﬁning standard inputs . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.1.5 Input summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.2 Drawing samples from a distribution . . . . . . . . . . . . . . . . . . . . . . . 22

2.2.1 Selecting an INPUT object and specifying the sampling method . . . . . 22

2.3 Switching between input objects . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.4 Enrichment of an experimental design with new samples . . . . . . . . . . . . 25

2.5 Performing an isoprobabilistic transform . . . . . . . . . . . . . . . . . . . . . 26

2.6 Adding bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.7 Deﬁning and using custom marginals . . . . . . . . . . . . . . . . . . . . . . . 27

2.7.1 Advanced options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.8 Constant variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3 Reference List 31

3.1 Creating an INPUT object: uq_createInput . . . . . . . . . . . . . . . . . . . 33

3.2 Getting samples from an INPUT object: uq_getSample . . . . . . . . . . . . . 37

3.3 Printing/Visualizing an INPUT object . . . . . . . . . . . . . . . . . . . . . . . 38

3.3.1 Printing information: uq_print . . . . . . . . . . . . . . . . . . . . . . 38

3.3.2 Graphical visualization: uq_display . . . . . . . . . . . . . . . . . . . 38

3.4 Enriching an existing sample set . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.4.1 Enriching a Latin Hypercube: uq_enrichLHS . . . . . . . . . . . . . . 39

3.4.2 Enriching a Sobol sequence: uq_enrichSobol . . . . . . . . . . . . . 40

3.4.3 Enriching a Halton sequence: uq_enrichHalton . . . . . . . . . . . . 40

3.4.4 Pseudo-LHS enrichment: uq_LHSify . . . . . . . . . . . . . . . . . . . 41

3.5 Sub-sampling an existing sample set: uq_subsample . . . . . . . . . . . . . . 42

3.6 Transforming samples between spaces . . . . . . . . . . . . . . . . . . . . . . 43

3.6.1 uq_GeneralIsopTransform . . . . . . . . . . . . . . . . . . . . . . . 43

3.6.2 uq_IsopTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.6.3 uq_NatafTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.6.4 uq_invNatafTransform . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.6.5 uq_RosenblattTransform . . . . . . . . . . . . . . . . . . . . . . . . 45

3.6.6 uq_invRosenblattTransform . . . . . . . . . . . . . . . . . . . . . . 45

3.7 Convenience functions to deﬁne marginals and copulas . . . . . . . . . . . . . 46

3.7.1 uq_Marginals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.7.2 uq_StdNormalMarginals . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.7.3 uq_StdUniformMarginals . . . . . . . . . . . . . . . . . . . . . . . . 47

3.7.4 uq_KernelMarginals . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.7.5 uq_GaussianCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.7.6 uq_PairCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.7.7 uq_VineCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.8 Additional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.8.1 uq_sampleU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.8.2 uq_MarginalFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

3.8.3 uq_estimateMoments . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.8.4 uq_setDefaultSampling . . . . . . . . . . . . . . . . . . . . . . . . . 53

3.8.5 uq_CopulaSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4 Appendices 55

A List of univariate distributions supported in UQLAB . . . . . . . . . . . . . . . 55

A.1 Uniform distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

A.2 Gaussian (Normal) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

A.3 Lognormal distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.4 Gumbel distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

A.5 Gumbel-min distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 59

A.6 Weibull distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

A.7 Gamma distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

A.8 Exponential distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 62

A.9 Beta distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

A.10 Triangular distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

A.11 Logistic distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

A.12 Laplace distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Chapter 1

Theory

1.1 Introduction

Identiﬁcation and modelling of the sources of uncertainty are crucial steps for the solution

of any uncertainty quantiﬁcation problem. In a probabilistic setting, each uncertain model

parameter can be represented by a random variable and a corresponding probability density

function (PDF) in the form X ∼ f

(x). Several input parameters, including their dependence

structure, can be grouped together in a random vector with joint PDF X ∼ f

(x). The INPUT

module in UQLAB offers a suite of tools to handle the representation, transformation and

sampling of a wide variety of univariate and joint PDFs.

Within the UQLAB framework, joint CDFs are represented by means of the copula formalism

(Nelsen, 2006). Copulas are a powerful tool to provide a simple representation of multivari-

ate distributions by separating the univariate distributions of each component of a random

vector (marginals) from their dependence structure (copula). The marginals and the copula

can thus be deﬁned and speciﬁed separately, as detailed in the next sections.

1.2 Representation of univariate distributions

A random variable X can be represented by its univariate cumulative distribution function

(CDF) F

(x) = P(X ≤ x). One then write X ∼ F

. The derivative f

of a continuous CDF

, if existing, is called the probability density function (PDF) of X.

1.2.1 Parametric distributions

UQLAB supports a number of continuous, differentiable distributions employed in many

ﬁelds of applied sciences, namely:

• Uniform

• Normal or Gaussian

• Lognormal

• Gumbel (maxima)

• Gumbel (minima)

• Beta

UQLAB user manual

• Gamma

• Exponential

• Weibull

• Triangular

• Logistic

• Laplace

In Appendix A, a more extensive overview of each distribution and its properties (e.g., PDF,

cumulative distribution function, support, moments, parameters) are given for reference.

1.2.2 Kernel density estimates

Kernel density estimation (KDE), also called kernel smoothing, is a non-parametric method

to infer a univariate distribution directly from data. Given a set X = {x

(1)

, . . . , x

(n)

} of n

independent identically distributed (i.i.d) observations from an unknown PDF f

, the KDE

estimate of f

is deﬁned as

(x) =

h=1

|x − x

(h)

. (1.1)

where k(·) is a non-negative function (kernel), which decays with the distance between the

point x where the distribution is evaluated and the point x

(h)

∈ X where the kernel is

centered. The parameter w, called the bandwidth, dictates how fast

decays with |x − x

(h)

A common choice for the kernel is the standard Gaussian distribution.

1.2.3 Truncated distributions

A truncated distribution results from restricting the support of a probability distribution.

Assume that a random variable X follows some distribution with CDF F

. Then, the CDF

and inverse CDF (“quantile function”) of the distribution truncated in [a, b] are deﬁned as

X|[a,b]

(x) = F

(x|a ≤ X ≤ b) and F

−1

X|[a,b]

(x) = F

−1

X|[a,b]

(x|a ≤ X ≤ b), respectively, and are

given by

X|[a,b]

(X) =











0 , X ≤ a

(X)−F

(a)

(b)−F

(a)

, a < X < b

1 , X ≥ b

(1.2)

and

−1

X|[a,b]

(u) =







a , u = 0

−1

(a) + u (F

(b) − F

(a))) , 0 < u < 1

b , u = 1

. (1.3)

A practical example of how truncated distributions are deﬁned in UQLAB is given in Sec-

tion 2.6.

1.2.4 Marginals inferred from data

UQLAB provides the possibility to infer marginals from data based on different goodness-of-

ﬁt criteria. More details about the theory underlying this topic and its usage in UQLAB are

UQLAB-V1.3-102 - 2 -

The Input module

provided in the UQLAB User Manual – Statistical inference.

1.3 Representation of dependencies through copulas

An M -dimensional copula (or M-copula for brevity) is formally deﬁned as a multivariate

distribution over [0, 1]

with uniform marginals in the unit interval. At the basis of the copula

formalism lies Sklar’s theorem, which states that, for any M -variate distribution F

of an M-

dimensional input random vector X = {X

, . . . , X

} with marginals F

, . . . , F

, there

exists a copula C such that

(x) = C(F

), F

), ..., F

)). (1.4)

Thus, the copula C is the function that links the marginals F

of a random vector to its joint

CDF F

. C itself does not depend on the F

, and purely describes the statistical interactions

among the components X

of X, that is, their dependence structure. Besides, C is unique if all

are continuous. The converse also holds: for any M -copula C and any set of marginals

, . . . , F

, the function F

given by (1.4) is a joint CDF with marginals F

, . . . , F

This property is exploited in UQLAB to deﬁne any joint distribution by specifying separately

its marginals and copula. This framework is ideal for uncertainty quantiﬁcation. Indeed,

it is often the case that marginal distributions as well as some form of correlation measure

between variables are known or inferred from available data, but no compound information

about the joint distribution is readily available.

A detailed description of the copula formalism and of the plethora of available copulas and

copula families is outside the scope of this manual. The reader is referred to Nelsen (2006)

and Joe (2015) for more details and relevant literature.

1.3.1 Sklar’s transformations for densities and conditional distributions

Relations analogous to (1.4) hold for probability densities and conditional distributions.

From (1.4) the joint PDF of X is obtained by differentiation:

(x) = c (F

), . . . , F

))

i=1

), (1.5)

where c(·) is the copula density function obtained as

c(u

, . . . , u

) =

∂

C(u

, . . . , u

)

∂u

. . . ∂u

. (1.6)

For conditional densities

,...,X

, . . . , x

) =

(x)

i=2

)

= c (F

), . . . , F

)) f

(1.7)

UQLAB-V1.3-102 - 3 -

UQLAB user manual

1.3.2 Some properties of copulas

As mentioned in Section 1.3, a copula describes the dependence between the random vari-

ables it couples, independent of their marginals. The following properties of copulas hold:

• Given two random vectors X and X

such that X

= α

), where α

(·) is a monotone

increasing transformation for each i = 1, . . . , M , then it is easy to prove that C

= C

;

• In particular, the random vector U such that U

= F

) has copula C

≡ C

;

• Since U has standard uniform marginals, C

is also its joint CDF;

• Thus, C

can be interpreted as the joint distribution of transformations of the original

random variables into random variables with standard uniform distribution.

Besides, a useful property is the following: the copula C

of the random vector X = (X

, X

)

such that X

and X

are mutually independent is given by

≡ C

· C

. (1.8)

(An analogous expression holds for the copula density c

of X). By recursion, the formula

trivially generalizes to any number of independent subgroups. This makes it possible to

easily express the joint copula density/distribution between independent groups of random

variables as the product of the individual copula densities/distributions.

1.4 Copulas currently available in UQLAB

UQLAB currently supports a variety of copula families to represent dependence between two

or more random variables. The currently supported families are brieﬂy characterized below.

1.4.1 Independent copula

C(u

, . . . , u

) =

i=1

(1.9)

By substituting Eq. (1.9) in (1.4), it is clear that it corresponds to the case in which the

components of the input random vector are independent. Indeed:

(x) = C(F

), . . . , F

)) =

i=1

). (1.10)

Consequently, the independent copula density is simply c(u

, . . . , u

) = 1. A graphical

representation of the independence copula PDF in dimension M = 2 is given for reference in

Figure 1, left panel.

UQLAB-V1.3-102 - 4 -

The Input module

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

Figure 1: Scatter plot and PDF contour plot of different pair copulas. From left to right:

independence copula, Gaussian copula with parameter ρ = 0.7, t- copula with parameters

ρ = 0.7, ν = 2, and Gumbel copula with parameter τ = 1.5.

1.4.2 Gaussian Copula

C(u

, . . . , u

; R) = Φ



−1

), . . . , Φ

−1

); R



(1.11)

where R is the linear correlation matrix of the multivariate Gaussian distribution associated

with the Gaussian copula, Φ

(u; R) is the cumulative distribution function of an M-variate

Gaussian distribution with mean 0 and correlation matrix R and Φ

−1

) is the inverse cu-

mulative distribution function of the standard normal distribution.

The Gaussian copula is one of the most commonly used copulas to parametrize the depen-

dence structure of random vectors with known marginals. If all the marginals as well as the

copula are Gaussian, the resulting joint PDF is also a multivariate normal distribution with

correlation matrix R. Another important property of the Gaussian copula is that a random

vector with Gaussian copula and diagonal correlation matrix R has independent components.

The Gaussian copula is asymptotically independent in both upper and lower tails. This means

that, no matter how high the parameter correlation coefﬁcient R

is, there will be no tail

dependence (see Nelsen (2006) for details).

A graphical representation of the Gaussian copula in dimension M = 2 is given for reference

in Figure 1, second panel.

1.4.3 Pair copulas

UQLAB supports a variety of parametric pair copulas to represent dependencies among

M = 2 random variables. These copula families cover different aspects of bivariate depen-

dence, such as upper or lower tail dependence, asymmetric tails, and others. While some of

these families admit an extension to the multivariate case (M > 2), this extension is typi-

cally non-unique and is not supported in UQLAB. Flexible multivariate families in UQLAB

are instead implemented in terms of vine copulas (see Section 1.4.4).

A list of pair copulas supported in UQLAB is provided in Table 1. The densities of some

of them, as well as samples drawn these densities, are illustrated in Figure 1. For each

supported pair copula density, UQLAB. provides its rotations by 90

◦

, 180

◦

, and 270

◦

. A pair

copula rotated by 90

◦

or 270

◦

transforms positive dependence into negative and vice versa; a

copula rotated by 180

◦

can be used to switch the upper and lower tails. These rotations are

UQLAB-V1.3-102 - 5 -

UQLAB user manual

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

0 0.5 1

0.2

0.4

0.6

0.8

Figure 2: Rotated Gumbel copula. From left to right: rotation by 0, 90, 180, and 270 degrees.

The copula parameter is ρ = 2.

deﬁned by the following equations:

(90)

(u, v) = v − C(1 − u, v),

(180)

(u, v) = u + v −1 + C(1 −u, 1 − v), (1.12)

(270)

(u, v) = u − C(u, 1 − v).

(Note that C

(90)

and C

(270)

are obtained by ﬂipping the copula density c around the vertical

and horizontal axis, respectively; some references provide the formulas for actual rotations:

(90)

(u, v) = v − C(v, 1 − u), C

(270)

(u, v) = u −C(1 − v, u)).

An example of rotated Gumbel pair copula is provided in Figure 2. The non-rotated Gumbel

copula assigns positive dependence as well as upper tail dependence to the random variables

it couples. The latter is visible as an accumulation of points in the upper right corner of

the unit square. The rotated versions implement negative dependence (rotations by 90

◦

and

270

◦

) or lower tail dependence (180

◦

1.4.4 Vine copulas

Flexible parametric families of multivariate copulas (M > 2) can be obtained by the product

of (possibly conditional) pair copulas. This construction, known as pair copula or vine con-

struction, was ﬁrst introduced by Bedford and Cooke (2002) and later popularized by Aas

et al. (2009). To get an intuition why this construction is possible, let us ﬁrst recall the chain

rule of probability which, in its version for probability densities, states that

(x) =

j=1

j|j+1,...,M

j+1

, . . . , x

), (1.13)

where f

j|j+1,...,M

is the conditional PDF of X

given X

j+1

, . . . , X

. Recalling (1.5),

c (F

), . . . , F

))

i=1

) =

j=1

j|j+1,...,M

j+1

, . . . , x

). (1.14)

Each conditional PDF on the right hand side of (1.14) can in turn be written in terms of a

pair copula density, that is a pair copula differentiated with respect to one of its arguments.

UQLAB-V1.3-102 - 6 -

The Input module

Table 1: Pair copula families supported in UQLAB. From left to right: copula name, CDF,

and parameter range. (a) Φ is the univariate standard normal distribution, and Φ

2;θ

is the

bivariate normal distribution with zero means, unit variances and correlation parameter θ.

(b) t

is the univariate t distribution with ν degrees of freedom, and t

ν,θ

is the bivariate t

distribution with ν degrees of freedom and correlation parameter θ.

Name C(u, v; θ) Parameter range

Independence uv

Clayton (u

−θ

+ v

−θ

− 1)

−1/θ

θ > 0

Frank −

log



1 − e

−θ

− (1 − e

−θu

)(1 − e

−θv

)

1 − e

−θ



θ ∈ R\{0}

Gaussian Φ

2;θ



−1

(u), Φ

−1

(v)



(a)

θ ∈ (−1, 1)

Gumbel exp



−((−log u)

+ (−log v)

)

1/θ



θ ∈ [1, + inf)

t- t

2;ν,θ



−1

(u), t

−1

(v)



(b)

ν > 1, θ ∈ (−1, 1)

Table 2: Some properties of pair copulas supported in UQLAB. Kendall’s tau, tail depen-

dence coefﬁcients, subfamilies of pair copulas that obtain for speciﬁc parameter values. See

also Torre et al. (2019).

Name τ

Special cases

Clayton

θ + 2

−1/θ

0 —

Frank 1 +

(

t(e

− 1)

−1

dt − 1) 0 0 —

Gaussian

arcsin(θ) 0 0 —

Gumbel

θ − 1

0 2 − 2

1/θ

—

arcsin(θ) λ

= λ

(d)

—

= 2t

ν+1



−

(ν + 1)(1 − θ)/(1 + θ)



To understand why, for a general subset of indices A ⊂ {1, . . . , M}, let F

i|A

, f

i|A

, , C

i|A

and

i|A

indicate the CDF, PDF, copula distribution and copula density of the random variable X

UQLAB-V1.3-102 - 7 -

UQLAB user manual

conditioned on X

, respectively. Joe (1996) showed that, for any (j, i) ∈ A ×A,

j|A

) =

∂C

ji|A\{i}

, u

)

∂u



j|A\{i}

A\{i}

), F

i|A\{i}

A\{i}

))

. (1.15)

Differentiating both sides with respect to u

yields

j|A

) = c

ji|A\{i}

j|A\{i}

A\{i}

), F

i|A\{i}

A\{i}

)) · f

j|A\{i}

A\{i}

). (1.16)

In other words, a conditional PDF can be written as the product between a pair copula and

a conditional PDF of lower order. The latter can be in turn be written as the product of

another pair copula and a conditional PDF of yet lower order, and so on. Eventually, one can

rewrite the right hand side of (1.14) as a product of (conditional) pair copulas multiplied by

). The latter factor appears in the left hand side of (1.14) too, and can be simpliﬁed.

In conclusion, the joint copula density is expressed as a product of pair copulas:

• M −1 unconditional pair copulas,

• M −2 pair copulas conditioned on 1 variable,

• . . .

• 1 pair copula conditioned on M −2 variables,

for a total of M(M −1)/2 pair copulas. Copulas expressed in this way are called vine copulas.

Note that the order of the variables used for the factorization in (1.14), as well as the index

i selected in (1.16), are arbitrary. Each choice corresponds to a different factorization of the

joint copula density into pair copula densities. To help organizing these different construc-

tions, Bedford and Cooke (2002) introduced two (non-exhaustive, but very broad) classes of

vine, representing two different choices for the vine factorization. These two classes, called

canonical (C-) and drawable (D-) vines, are supported in UQLAB and are deﬁned as follows.

• C-vine

c(u) =

M−1

j=1

M−j

i=1

j,j+i|{1,...,j−1}

j|{1,...,j−1}

, u

j+i|{1,...,j−1}

), (1.17)

A C-vine thus expresses an M-copula as a tensor product of

– M −1 pair copulas between variable X

and X

, j = 2, . . . , M,

– M −2 pair copulas between X

and X

conditioned on X

, j = 3, . . . , M,

– . . .

– the pair copula between X

M−1

and X

, conditioned on X

, . . . , X

M−2

A graphical representation is provided in Figure 3, left panel.

• D-Vine

c(u) =

M−1

j=1

M−j

i=1

i,i+j|{i+1,...,i+j−1}

i|{i+1,...,i+j−1}

, u

i+j|{i+1,...,i+j−1}

). (1.18)

UQLAB-V1.3-102 - 8 -

The Input module

1,2

1,3

1,4

1,5

2,3

2,4

2,5 |1

3,4 |1,2

3,5

|1,2

4,5

|1,2,3

1,2

2,3

3,4

4,5

1 2 3 4 5

1,3 |2

2,4 |3

3,5 |4

1 2 3 4 5

1,4 |2,3

2,5 |3,4

1 2 3 4 5

1,5 |2,3,4

1 2 3 4 5

Figure 3: Graphical representation of C- and D-vines. The pair copulas in each tree of a

5-dimensional C-vine (left; conditioning variables are shown in grey) and of a 5-dimensional

D-vine (right; conditioning variables are those between the connected nodes).

A D-vine thus expresses an M-copula as a tensor product of

– M −1 unconditional pair copulas between variable X

and X

i+1

, i = 1, . . . , M −1,

– M −2 pair copulas between X

and X

i+2

conditioned on X

i+1

, i = 1, . . . , M − 2,

– . . .

– the pair copula between X

and X

, conditioned on X

, . . . , X

M−1

A graphical representation of this structure is provided in the right panel of Figure 3.

C- and D-vine constructions require in general to specify different sets of pair copulas (except

when M = 3, in which case each D-vine is a C-vine and vice versa). Thus, one may prefer one

construction or the other depending on the type of information available. Besides, the pair

copulas involved in each of the two classes are fully determined by the order of the variables

, . . . , X

. An M-copula thus admits a factorization into M!/2 different C-vines and M!/2

different D-vines (the two classes being equivalent if M = 3).

Truncated vines. The pair copulas that a vine comprises can be grouped into different trees.

The ﬁrst tree consists of all independent M − 1 unconditional pair copulas, the second tree

of all M − 2 pair copulas between random variables conditioned on another single variable,

and so on until the M − 1-th and last tree, consisting of a single pair copula between two

random variables conditioned on all other variables. In equations (1.17) and (1.18), the tree

index is represented by the variable j.

A vine is said to be truncated at level t

∗

∈ {1, . . . , M − 1}, if all pair copulas belonging to

any tree t ≥ t

∗

are the independence pair copula. The rationale for working with truncated

vines is that, often, only conditional probabilities of low order can be reasonably asserted or

reliably inferred from data, whereas imposing complex models for conditional probabilities

UQLAB-V1.3-102 - 9 -

UQLAB user manual

of higher order may correspond to over-interpreting or over-ﬁtting data. Furthermore, con-

ditional probabilities of higher order typically have a weaker effect on the joint PDF of the

input random variables than those of lower order, especially if the strongest correlations are

captured in earlier trees, and can thus be neglected.

1.4.5 Copulas inferred from data

In addition to user-deﬁned parametric copulas, UQLAB supports the possibility to infer cop-

ulas from data. The theory underlying this topic and its usage in UQLAB are extensively

covered in the companion UQLAB User Manual – Statistical inference.

1.5 Sampling random vectors

Various uncertainty quantiﬁcation tasks require to generate data according to a speciﬁed

joint distribution. For instance, resampling from a known distribution of the inputs to a

system enables statistical estimation of the output by Monte-Carlo or by more sophisticated

strategies.

A number of random sampling strategies (e.g. Monte Carlo sampling, latin hypercube sam-

pling (LHS), pseudorandom sequences, etc.) are available to produce samples in the stan-

dard uniform space, that is, for Z ∼ U([0, 1]

). A possible strategy to sample from a different

distribution F

is thus to transform a sample z of Z into a sample x of X, if such a trans-

formation exists. Maps of the form (Lebrun and Dutfoy, 2009)

X = T (U ) s.t. X ∼ F

, U ∼ F

, (1.19)

which transform a random vector U ∼ F

(or a sample u thereof) into a random vector

X ∼ F

(or a sample x therefore) are called isoprobabilistic transforms. Amongst the many

strategies available to generate samples distributed according to a more general distribution

, UQLAB makes use of isoprobabilistic transforms. Of particular interest for generating

samples of X ∼ F

are isoprobabilistic transforms from U ∼ U([0, 1]

) to X . In the

following, isoprobabilistic transforms to different target distributions F

will be derived. We

will see that different transforms exist depending on the copula of C

of F

1.5.1 Independence copula: probability integral transform

A well known result of probability theory states that, for any random variable X with contin-

uous CDF F

, the random variable

U = F

(X) (1.20)

is uniformly distributed in the unit interval: U ∼ U([0, 1]). The map (1.20) is also known as

probability integral transform (PIT) of X. Its inverse

X = F

−1

(U) (1.21)

UQLAB-V1.3-102 - 10 -

The Input module

thus maps U ∼ U([0, 1]) into X ∼ F

. The inverse PIT provides a simple way

to transform an M-variate sample U =



(1)

, . . . , u

(N)



∼ U([0, 1]

) into a sample

X =



(1)

, . . . , x

(N)



∼ F

, for any multivariate distribution F

with independent marginals

– that is, with independent copula (1.9). For all i = 1, . . . , N and all j = 1, . . . , M ,

(i)

= F

−1

(i)

). (1.22)

We call (1.22) the inverse PIT for random vectors.

1.5.2 Gaussian copula: Nataf transform

In the case of dependent variables, several extra steps are needed to transform a sample set

distributed according to U([0, 1]

) into a sample set with the desired joint PDF. When the

target joint PDF has Gaussian copula, a powerful tool to achieve this goal is the inverse Nataf

transform.

We ﬁrst recall a fundamental result of probability theory: Gaussian random variables are

mutually independent if and only if they are uncorrelated. Based on this property, a Gaussian

random vector V with correlation matrix R can be transformed into a Gaussian random

vector W with uncorrelated (and therefore independent) components by

W = Γ

−1

V , (1.23)

where Γ

−1

is the inverse Choleski factor of R, satisfying the matrix equation ΓΓ

= R.

The Nataf transform maps a random vector X with Gaussian copula C

given by (1.11) and

arbitrary continuous marginals F

into W ∼ N(0, I

), where I

is the identity matrix in

, in three steps:

• X 7→ U ∼ C

: U

= F

) ∼ U([0, 1]) (PIT of X)

• U 7→ V ∼ N(0, R) : V

= Φ

−1

) ∼ N([0, 1]), where Φ is the standard normal CDF

• V 7→ W ∼ N(0, I

) through (1.23).

The ﬁrst two steps involve monotonically increasing transformations of the marginals, thus

do not change the Gaussian copula of X (see Section 1.3.2). Therefore, V has standard

Gaussian marginals and Gaussian copula, that is, Gaussian joint PDF. Consequently, the ran-

dom vector W obtained by the last step is indeed multivariate standard normal. The inverse

map, called inverse Nataf transformation, maps the standard normal space to the space with

probability measure F

To further map W onto the uniform standard space, only the marginals of W need to be

transformed, by

• W 7→ Z : Z

= Φ(W

The inverse transformation is used to map the standard uniform space into the probability

space identiﬁed by F

, and thus to sample from F

. It reads:

UQLAB-V1.3-102 - 11 -

UQLAB user manual

1. Z 7→ W ∼ N(0, I

) : W

= Φ

−1

)

2. W 7→ V = Γ U ∼ N(0

, R)

3. V 7→ U ∼ C

: U

= Φ(V

)

4. U 7→ X ∼ F

: X

= F

−1

)

1.5.3 Other copulas: Rosenblatt transform

The most general case of generating samples with an arbitrary M -dimensional copula can be

addressed by making use of the inverse Rosenblatt transform. First introduced by Rosenblatt

(1952), The Rosenblatt transform maps a random vector X with continuous marginals into

a random vector Z with independent, U([0, 1]) components. It reads











= F

)

= F

)

= F

,...,X

M−1

, . . . , X

M−1

)

. (1.24)

Within the copula formalism, one can perform the transform in two steps:

• X 7→ U ∼ C

, by the PIT (1.20)

• U 7→ Z : Z

= C

,...,X

i−1

, . . . , u

i−1

The transformation is invertible (all conditional distributions are monotonically increasing).

Its inverse can be used to generate samples of X from samples of Z.

The applicability of the inverse Rosenblatt transform requires knowledge of the conditional

quantile functions C

−1

,...,X

i−1

, . . . , u

i−1

), i = 1, . . . , M. While these are not available

for all classes of parametric copulas, they are for some (at least numerically), including vine

copulas (for details, see Aas et al. (2009)). UQLAB provides algorithms to sample from C- and

D-vines, and uses an original implementation that capitalizes on the efﬁcient vectorization of

the numerical inversion process.

Note: while the inverse Rosenblatt transform is a valid alternative to the inverse Nataf

transform for Gaussian copulas, it is computationally less efﬁcient. The latter is

therefore used by UQLAB in the presence of a Gaussian copula.

UQLAB-V1.3-102 - 12 -

Chapter 2

Usage

2.1 Deﬁning an INPUT object

As discussed in the theory chapter, a random vector in UQLAB is deﬁned by its marginal

distributions and the copula that deﬁnes their dependence structure. Marginals and copula

can be deﬁned independently from each other, and together fully determine the joint PDF of

the input via the relation (1.4).

2.1.1 Deﬁning the input marginals

2.1.1.1 The general case

An M-dimensional input requires the speciﬁcation of M marginal distributions.

The following code deﬁnes a bivariate Gaussian random vector X = [X

, X

]

with inde-

pendent components (independence copula). The mean value and standard deviation of X

(resp. X

) are µ

= 1, σ

= 1 (resp. µ

= 2, σ

= 0.5):

uqlab;

Input.Marginals(1).Type = 'Gaussian';

Input.Marginals(1).Parameters = [1 1];

Input.Marginals(2).Type = 'Gaussian';

Input.Marginals(2).Moments = [2 0.5];

myInput1 = uq_createInput(Input);

Note that the copula has not been explicitly assigned: when not deﬁned, UQLAB by default

assumed it to be the independence copula (1.9). The corresponding code is (to be typed

before using uq_createInput):

Input.Copula.Type = 'Independent';

Also note that the ﬁrst and second marginals have been speciﬁed through their parameters

and moments, respectively. For every marginal, either information is accepted, but not both.

When the INPUT object myInput1 is created, all parameters and moments for all variables

are computed and possible inconsistencies are checked.

UQLAB user manual

2.1.1.2 Special cases of univariate distributions

Most of the available (built-in) distributions can be deﬁned similarly to the way a Gaussian

distribution was deﬁned in Section 2.1.1.1, i.e., either by deﬁning the two parameters of the

distribution or its moments (mean and standand deviation). The meaning of the parameters

is as described in Appendix A. Some special cases are the following:

• For the exponential distribution only one parameter (λ) exists. When such a distribution

is deﬁned by its parameters only one element is needed (λ). Additionally when it is

deﬁned by its moments only one element is needed again which corresponds to the

mean and standard deviation (that are equal).

• For the beta distribution there is the possibility of using four parameters when a custom

support [a, b] needs to be deﬁned. For example, in order to deﬁne an element of an

input vector that follows a beta distribution with parameters [r, s] = [1, 2] and support

[a, b] = [0.5, 1.5] we do the following:

Input.Marginals.Type = 'Beta';

Input.Marginals.Parameters = [1, 2, 0.5, 1.5];

Similarly, we can deﬁne a beta distribution with moments [µ, σ] = [0.8, 0.2] and support

[a, b] = [0.5, 1.5] as follows:

Input.Marginals.Type = 'Beta';

Input.Marginals.Moments = [0.8, 0.2, 0.5, 1.5];

In this case the two parameters r, s are computed according to the equations in Sec-

tion A.9.

• A marginal obtained through kernel smoothing on a data set X can be represented by

Input.Marginals.Type = 'KS';

Input.Marginals.Parameters = X;

which by default uses a Gaussian kernel with bandwidth optimized on the data. The

additional subﬁeld .Options can be used to optionally specify the kernel type, band-

width, and the distribution bounds. For instance, the additional lines of code

Input.Marginals.Options.Bandwidth = 0.1;

Input.Marginals.Options.Bounds = [0, 5];

specify that a kernel bandwidth w = 0.1 must be used, and that the KDE distribution

must be truncated within the interval [0, 5].

2.1.1.3 Marginals inferred from data

The code needed to instruct UQLAB to infer the marginals from data is explained in detail in

the companion UQLAB User Manual – Statistical inference.

UQLAB-V1.3-102 - 14 -

The Input module

2.1.1.4 Convenience functions for speciﬁc marginals

A number of convenience functions are available to quickly generate data structures that

deﬁne marginals of speciﬁc types:

• uq_Marginals can be used to conveniently generate any given number of marginals of

the same parametric family and parameters (or moments);

• uq_StdUniformMarginals speciﬁcally generates standard uniform marginals;

• uq_StdNormalMarginals speciﬁcally generates standard normal marginals;

• uq_KernelMarginals speciﬁcally generates marginals by kernel smoothing.

For more details on these functions, see Section 3.7.

2.1.2 Deﬁning the input copula

Let us now create another INPUT object where dependency between the marginals is intro-

duced by imposing a copula. Below, various parametric copulas supported by UQLAB are

covered. For copulas inferred from data, see the companion UQLAB User Manual – Statisti-

cal inference.

2.1.2.1 Gaussian copula

As discussed in Section 1.4.2, the Gaussian copula takes as parameter the linear correla-

tion matrix R of the copula, which is here taken to be R =



1 0.8

0.8 1



(linear correlation

coefﬁcient ρ

= 0.8).

Input.Name = 'Input 2: Dependent marginals' ;

Input.Copula.Type = 'Gaussian';

Input.Copula.Parameters = [ 1 0.8 ; 0.8 1 ];

myInput2 = uq_createInput(Input);

X = uq_getSample(300);

The resulting samples are plotted in Figure 4. By default the sampling method that is

used is Monte Carlo. Also notice that we can assign custom names to an INPUT object, e.g.

'Input 2: Dependent marginals' in the present case.

Note: The code above assumes that the ﬁelds Input.Marginals have been previ-

ously assigned, as in Section 2.1.1.1. In other words, after creating the IN-

PUT myInput1, we replace the independence copula by the Gaussian one in the

Input.Copula ﬁeld, and create a second INPUT myInput2.

2.1.2.2 Pair copula

A pair copula is deﬁned in UQLAB by

Input.Copula.Type = 'Pair';

UQLAB-V1.3-102 - 15 -

UQLAB user manual

-1 0 1 2 3 4

0.5

1.5

2.5

3.5

Figure 4: Samples drawn from a 2-D Gaussian distribution with a Gaussian copula (correla-

tion coefﬁcient ρ

= 0.8).The sampling method is plain Monte Carlo.

Additionally, the copula’s Family and Parameters must be provided. As an optional argu-

ment, pair copula densities of standard parametric families can be rotated by 90, 180 or 270

degrees through the additional ﬁeld Rotation.

The code below deﬁnes a Clayton pair copula (see Table 1), whose density is rotated by 90

◦

This allows us to introduced a negative correlation between the coupled random variables

and X

. Beside, the non-rotated Clayton pair copula has lower tail dependence coefﬁ-

cient. Therefore, its rotated version assigns lower tail dependence between −X

and X

, as

apparent from the cloud of points extending into the lower right corner of Figure 5.

Input.Name = 'Input 3: Negative correlation';

Input.Copula.Type = 'Pair';

Input.Copula.Family = 'Clayton';

Input.Copula.Rotation = 90;

Input.Copula.Parameters = 1.5;

myInput3 = uq_createInput(Input);

X = uq_getSample(300);

2.1.2.3 Vine copula: C-Vine and D-Vine

Specifying a higher-dimensional copula by vine construction (see Section 1.4.4) requires to

deﬁne all comprising pair copulas. The vine structure speciﬁes which of the M!/2 possible

orders of the variables is chosen for the construction, and thus which set of pair copulas are

explicitly provided in the vine construction. UQLAB currently supports two classes of vines:

UQLAB-V1.3-102 - 16 -

The Input module

-2 0 2 4

Figure 5: Monte Carlo samples drawn from a 2-D distribution with Gaussian marginals and

Clayton copula (ρ = 1.5) rotated by 90

◦

canonical (C-) vines and drawable (D-) vines.

The example below constructs a 3-dimensional C-vine obtained as a tensor product of pair

copula densities c

, c

and c

13|2

, that is, vine structure 2 − 1 − 3. The three copulas are,

respectively: a 't'- copula with parameters [.4, 2], a 'Frank' copula with parameter 0.5,

and the 'Independence' copula. The third variable is assigned an exponential marginal. A

sample set from this distribution is shown in Figure 6.

Input.Name = 'Input 4: 3D C-Vine' ;

Input.Marginals(1).Type = 'Gaussian';

Input.Marginals(1).Parameters = [1 1];

Input.Marginals(2).Type = 'Gaussian';

Input.Marginals(2).Moments = [2 0.5];

Input.Marginals(3).Type = 'Exponential';

Input.Marginals(3).Parameters = 1.5;

Input.Copula.Type = 'CVine';

Input.Copula.Structure = [2 1 3];

Input.Copula.Families = {'t', 'Frank', 'Independence'};

Input.Copula.Rotations = [0, 0, 0];

Input.Copula.Parameters = {[.4, 2], .5, []};

myInput4 = uq_createInput(Input);

X = uq_getSample(300);

For a complete list of options to specify for a vine copula, see Table 6 and Table 8.

The set of pair copulas that a vine comprises are often not easy to keep track of, especially

with higher dimension M. This information can be retrieved by the code below (for a 4-

UQLAB-V1.3-102 - 17 -

UQLAB user manual

0 5 10

0 2 4

-5 0 5

-5

Figure 6: Monte Carlo samples drawn from a 3-D distribution with C-vine copula.

dimensional 'CVine' with structure [4 1 2 3]):

uq_CopulaSummary('CVine', [4 1 3 2]);

which prints the text:

CVine, dimension 4, structure [4 1 3 2]. Pair copulas:

Index | Pair Copula

==================================

1 | C_4,1

2 | C_4,3

3 | C_4,2

4 | C_1,3|4

5 | C_1,2|4

6 | C_3,2|4,1

For a detailed use of the function uq_CopulaSummary, see Section 3.8.5.

2.1.2.4 Truncated vines

As discussed in Section 1.4.4, the higher-order dependencies needed for the construction of

a vine copula may be difﬁcult to assert, or to reliably infer from data. Also, when setting the

vine structure such that pair copulas among more strongly correlated random variables are

captured in earlier trees, higher-order dependencies play a less signiﬁcant role in shaping the

joint PDF and can often be neglected. This is also the approach taken by UQLAB and by most

software when inferring vine copulas from data (see the UQLAB User Manual – Statistical

inference, Section 1.3.3).

UQLAB-V1.3-102 - 18 -

The Input module

Table 3: Number of non-truncated pair copulas for a vine of dimension M truncated at tree

t. The last row, where t = M, corresponds to the no-truncation case and indicates the total

number of pair copulas in the vine.

∗

: no truncation, because t ≥ M: all pair copulas need

to be speciﬁed.

3 4 5 6 7 8 9 10

2 2 3 4 5 6 7 8 9

3 3

∗

5 7 9 11 13 15 17

4 3

∗

9 12 15 18 21 24

5 3

∗

14 18 22 26 30

M 3 6 10 15 21 28 36 45

Representing a vine truncated at tree t is possible by using the additional code

Input.Copula.Truncation = t;

for any t = 1, . . . , M, where t = 1 sets all pair copulas to the independence pair copula,

and thus the vine to the independence M-copula, and t = M corresponds to no truncation.

Values of t lower than 1 or larger than M are also interpreted by UQLAB as no truncation.

Note: For a vine truncated at level t, only the pair copulas in the ﬁrst t − 1 trees need

to be speciﬁed. The others are by deﬁnition the independence copula.

Since the j-th tree contains M −j copulas, a total of (M −1) + (M −2) + . . . + (M −t −1) =

(t − 1)M − t(t + 1)/2 are to be deﬁned (see Table 3 for the number of non-truncated pair

copulas in a vine for different values of M and t). UQLAB additionally handles several special

cases as follows:

• an error is thrown if not enough or too many pair copulas are speciﬁed (for instance, if

M = 10, t = 3 and less than 17 or more than 45 pair copulas are provided);

• a warning is given if more pair copulas than the non-truncated ones are speciﬁed (for

instance, if M = 10, t = 3 and more than 17 pair copulas are provided).

2.1.3 Independent subgroups of random variables

As mentioned in Section 1.3.2, the copula of a random vector consisting of independent

subgroups of random variables is given by the product of the copulas of all subgroups (see

(1.8) for the case d = 2). Subgroup independence can be speciﬁed in UQLAB by simply

deﬁning any number of input copulas, and the variables associated to each one. The full

copula is automatically understood to be the tensor product of the individual copulas. For

instance, the code below deﬁnes an input consisting of 5 standard normal random variables,

three of which (X

, X

and X

) are coupled by a Gaussian copula, the remaining coupled by

a Gumbel pair copula:

UQLAB-V1.3-102 - 19 -

UQLAB user manual

iOpts = struct;

iOpts.Marginals = uq_StdNormalMarginals(5);

iOpts.Copula(1).Type = 'Gaussian';

iOpts.Copula(1).RankCorr = [1 .5 -.3; .5 1 .2; -.3 .2 1];

iOpts.Copula(1).Variables = [1 4 5];

iOpts.Copula(2).Type = 'Pair';

iOpts.Copula(2).Family = 'Gumbel';

iOpts.Copula(2).Parameters = 1.5;

iOpts.Copula(2).Variables = [2 3];

myInput = uq_createInput(iOpts);

uq_print(myInput)

==============================================================

Input object name: Input 7

Dimension(M): 5

Marginals:

Index | Name | Type | Parameters | Moments

---------------------------------------------------------------------

1 | X1 | Gaussian | 0.00e+00, 1.00e+00 | 0.00e+00, 1.00e+00

2 | X2 | Gaussian | 0.00e+00, 1.00e+00 | 0.00e+00, 1.00e+00

3 | X3 | Gaussian | 0.00e+00, 1.00e+00 | 0.00e+00, 1.00e+00

4 | X4 | Gaussian | 0.00e+00, 1.00e+00 | 0.00e+00, 1.00e+00

5 | X5 | Gaussian | 0.00e+00, 1.00e+00 | 0.00e+00, 1.00e+00

Copula:

Tensor product of 2 copulas between the random vectors

X_[1 4 5], X_[2 3]

Copula 1, of X_[1 4 5]:

Type: Gaussian

Dimension: 3

Variables coupled: [1 4 5]

Parameters:

[+1.0000 +0.5176 -0.3129 ;

+0.5176 +1.0000 +0.2091 ;

-0.3129 +0.2091 +1.0000 ]

Copula 2, of X_[2 3]:

Type: Pair

Variables coupled: [2 3]

Family: Gumbel

Rotation: 0

Parameters: 1.5

==============================================================

All copula types can be freely combined, and there is no restriction on their individual pa-

rameters.

UQLAB-V1.3-102 - 20 -

The Input module

2.1.4 Deﬁning standard inputs

Some multivariate distributions are often used in various types of statistical analysis. This is

the case of the M-variate standard uniform (resp. standard normal) distributions, that is, dis-

tributions with U([0, 1]) (resp. N(0, 1)) marginals and independence copula. The following

code employs convenience functions to generate a 10-dimensional standard uniform/Gaus-

sian random vector:

myInput1 = uq_StdNormalInput(10);

myInput2 = uq_StdUniformInput(10);

If one wants only the marginals to be the standard ones from a speciﬁc family (e.g. Gaussian),

but needs to assign a copula myCopula other than the independence one, the following code

can be used:

Input.Marginals = uq_StdNormalMarginals(10);

Input.Copula = myCopula;

myInput1 = uq_createInput(Input);

(For details on how to specify the copula, see Section 2.1.2).

For a comprehensive list of all the available convenience functions in the INPUT module,

please refer to Section 3.7

2.1.5 Input summary

Once an INPUT object has been created, a summary of its marginals and copulas can be

printed on screen via the uq_print command.

Input.Marginals(1) = uq_Marginals(1, 'Gaussian', [2 0.5]);

Input.Marginals(2) = uq_Marginals(1, 'Gaussian', [1 1]);

Input.Copula = uq_GaussianCopula([1 .8; .8, 1]);

myInput1 = uq_createInput(Input);

uq_print(myInput1)

==============================================================

Input object name: Input 1

Dimension(M): 2

Marginals:

Index | Name | Type | Parameters | Moments

--------------------------------------------------------------------------

1 | X1 | Gaussian | 2.000e+00, 5.000e-01 | 2.000e+00, 5.000e-01

2 | X2 | Gaussian | 1.000e+00, 1.000e+00 | 1.000e+00, 1.000e+00

Copula:

Type: Gaussian

Dimension: 2

Variables coupled: [1 2]

Parameters:

[+1.0000 +0.8000 ;

UQLAB-V1.3-102 - 21 -

UQLAB user manual

+0.8000 +1.0000 ]

==============================================================

For visual inspection of an INPUT object, the function uq_display can be used as follows:

uq_display(myInput1)

The result is shown in Figure 7.

Figure 7: The output of the function uq_display on the INPUT object myInput1. By default,

the samples are drawn using Monte Carlo sampling.

2.2 Drawing samples from a distribution

It is possible to draw samples from the INPUT object myInput1 as follows:

X = uq_getSample(300);

Notice that we do not need to deﬁne the INPUT object in uq_getSample, because after an

INPUT object is created, if not speciﬁed otherwise, it is the one that is going to be used

when calling uq_getSample. Methods to handle different INPUT objects in the workspace

are described in Section 2.3. The MATLAB standard random number generator is used by

default.

2.2.1 Selecting an INPUT object and specifying the sampling method

When handling several INPUT objects in parallel, the last one that has been deﬁned is used

by default for sampling. There are two ways to use an INPUT object different from the last

UQLAB-V1.3-102 - 22 -

The Input module

deﬁned one:

• Using the function uq_selectInput. For example, drawing 300 samples from the IN-

PUT object myInput1 can be achieved as follows:

uq_selectInput(myInput1);

X = uq_getSample(300);

• Specifying the INPUT object directly in uq_getSample. For example, drawing 300 sam-

ples from the INPUT object myInput1 can be achieved as follows:

X = uq_getSample(myInput1, 300);

When using uq_getSample in order to obtain samples from a random vector, various sam-

pling methods can be used. For instance Latin Hypercube Sampling (McKay et al., 1979) can

be used to sample from the INPUT object myInput2 as follows:

X = uq_getSample(300, 'LHS');

The result is shown in Figure 8. For a list of all the available sampling methods refer to

Table 11 in Section 3.2.

Figure 8: Samples drawn from INPUT myInput1 using the Latin Hypercube sampling method.

Advanced options

Instead of using the 'LHS' argument in uq_getSample one could also change the default

sampling method of the INPUT object myInput2 as follows:

uq_selectInput(myInput1);

UQLAB-V1.3-102 - 23 -

UQLAB user manual

uq_setDefaultSampling('LHS');

Note that this does not affect other INPUT objects, i.e.the sampling method for myInput1 is

still plain Monte Carlo.

2.3 Switching between input objects

Suppose we want to draw two sample sets:

• 200 Monte Carlo samples from the input vector myInput1 deﬁned above, and having

components coupled by a Gaussian copula;

• 300 LHS samples from the input vector myInput2 deﬁned right below, whose marginal

is bounded and independent from X

Input2.Marginals(1) = uq_Marginals(1, 'Gaussian', [2 0.5]);

Input2.Marginals(2).Bounds = [-3, 2];

Input2.Marginals(2) = uq_Marginals(1, 'Gaussian', [1 1]);

myInput2 = uq_createInput(Input2);

This is carried out as follows:

uq_selectInput(myInput1);

X2 = uq_getSample(200,'MC');

uq_selectInput(myInput2);

X3 = uq_getSample(300,'LHS');

The two samples are plotted in Figure 9.

Figure 9: Samples drawn from two different cases of a 2-D Gaussian distribution. The INPUT

object myInput2 has dependent marginals and the INPUT object myInput3 has independent

marginals and bounds on X

∈ [−3, 2]. The sampling method is Latin Hypercube sampling.

UQLAB-V1.3-102 - 24 -

The Input module

2.4 Enrichment of an experimental design with new samples

Enrichment is a functionality that can be used when there is an already existing sample set

(called experimental design in the context of metamodelling) to which more points need to

be added. Starting from where the previous section (Figure 8) left off, assume that we want

to add 700 additional points to the Latin Hypercube (the already existing 300 samples are

stored in X):

Xnew = uq_enrichLHS(X, 700);

-2 0 2 4

0.5

1.5

2.5

3.5

Xnew

Figure 10: Enrichment of the LHS samples drawn from a 2-D Gaussian distribution with a

Gaussian copula using uq_enrichLHS. The initial sample set is shown in Figure 8.

Note: uq_enrichLHS only returns the new sample points! The full set can be retrieved

by Xfull = [X;Xnew].

However, uq_enrichLHS should only be used when the initial sample set is generated by

Latin Hypercube sampling. If the initial sample set X was generated, e.g. using plain Monte

Carlo or if its origin is unknown (e.g. because it has been produced by another software)

then the function uq_LHSify must be used. This function enriches the existing sample set in

such a way that it forms a pseudo-Latin Hypercube sampling as a whole. This can be done as

follows:

Xnew = uq_LHSify(X, 700);

Xfull = [X;Xnew];

For enriching an experimental design that was generated by Sobol or Halton sampling the

functions uq_enrichSobol and uq_enrichHalton can be used with a similar syntax. For

more information about the available sample enrichment functions see Section 3.4.

UQLAB-V1.3-102 - 25 -

UQLAB user manual

2.5 Performing an isoprobabilistic transform

Isoprobabilistic transforms are implemented in a general fashion in UQLAB. Assume that

we want to map some existing sample X to the standard normal space (e.g. for solving a

reliability problem, see Section 1 of UQLAB User Manual – Structural Reliability).

This can be carried out by deﬁning the marginals (here, standard normal) and copula (here,

independent) of the target vector U.

UMarginals(1).Type = 'Gaussian';

UMarginals(1).Parameters = [0,1];

UMarginals(2).Type = 'Gaussian';

UMarginals(2).Parameters = [0,1];

UCopula.Type = 'Independent';

Then the transformed samples are obtained by:

U = uq_GeneralIsopTransform(X,...

myInput2.Marginals, myInput2.Copula, UMarginals, UCopula);

The original and transformed samples are shown in Figure 11.

-4 -2 0 2 4

-4

-2

-4 -2 0 2 4

-4

-2

Figure 11: Isoprobabilistic transform from the physical space (2D Gaussian, left) to the stan-

dard normal space (right).

2.6 Adding bounds

A marginal distribution truncated (oa.k.a bounded) in an interval [a, b] which is contained in

the distribution’s domain can be speciﬁed by

Input.Marginals(1).Bounds = [a b];

For instance, the code below deﬁnes an uncorrelated 2D Gaussian distribution with X

(resp.

) having mean value µ

= 1 (resp. µ

= 3) and standard deviation σ

= 2 (resp. σ

= 2).

Additionally, X

is bounded in [−3, 2]:

UQLAB-V1.3-102 - 26 -

The Input module

Input.Marginals(1).Type = 'Gaussian';

Input.Marginals(1).Parameters = [1 2];

Input.Marginals(1).Bounds = [-3 2];

Input.Marginals(2).Type = 'Gaussian';

Input.Marginals(2).Moments = [2 2];

myInput3 = uq_createInput(Input);

Now we can draw 300 samples using Latin Hypercube Sampling as follows:

X = uq_getSample(300, 'LHS');

The result is shown in Figure 12.

-4 -2 0 2 4

-2

Figure 12: Samples drawn from a 2-D Gaussian distribution with independent marginals and

bounds on X

∈ [−3, 2]. The sampling method is Latin Hypercube sampling.

2.7 Deﬁning and using custom marginals

The built-in probability distributions can be found in Table 5 of the Reference List (Section 3)

and a brief description of each in Section 1.2. New distributions can be deﬁned by providing

three ﬁles ()within a folder that is available to the MATLAB path), each corresponding to the

PDF, CDF and inverse CDF respectively. In order to deﬁne a new distribution the following

naming convention has to be followed. The functions that correspond, e.g., to a distribution

called myDistribution should be named as follows:

• PDF function: uq_myDistribution_pdf

• CDF function: uq_myDistribution_cdf

UQLAB-V1.3-102 - 27 -

UQLAB user manual

• inverse CDF function: uq_myDistribution_invcdf

The deﬁnition of each function should look like:

function f = uq_myDistribution_pdf(X, parameters)

function F = uq_myDistribution_cdf(X, parameters)

function X = uq_myDistribution_invcdf(F, parameters)

The input arguments X and F of these functions are vectors of length N and parameters is

a vector of doubles of arbitrary length.

In order to use the custom distribution myDistribution we then create an INPUT object as

follows:

Input.Marginals(1).Type = 'myDistribution';

Input.Marginals(1).Parameters = ...

% e t c .

myInput = uq_createInput(Input);

2.7.1 Advanced options

On top of the three functions deﬁned above, the user may deﬁne an additional function that

computes the distribution moments from its natural parameters as followa

function moments = uq_myDistribution_PtoM(parameters)

where parameters is an array of arbitrary size containing the distribution parameters and

moments is the vector [µ, σ] containing the mean and standard deviation of the distribution

for the given parameter values.

Note: In case the function uq_myDistribution_PtoM is not provided the moments of

the distribution are estimated numerically. For more information refer to the

uq_estimateMoments function reference (Section 3.8.3). The default values of

the options of uq_estimateMoments are used for estimating the moments.

In addition, the function that calculates the parameters of a user-deﬁned probability distri-

bution given its moments must be speciﬁed in case the user wants to deﬁne the distribution

based on its moments, rather than on its parameters specifying the distribution based on its

mean and standard deviation is required. In this case, a function of the following form is

required:

function parameters = uq_myDistribution_MtoP(moments)

where moments is a vector equal to [µ, σ], that is the mean and standard deviation of the

distribution and parameters is a vector that contains the distribution’s parameters that

correspond to the given moments.

UQLAB-V1.3-102 - 28 -

The Input module

2.8 Constant variables

Constants are degenerate random variables that always take the same scalar value. A con-

stant variable can be speciﬁed as follows:

Input.Marginals.Type = 'Constant';

Input.Marginals.Parameters = 1;

A random variable with zero variance is automatically interpreted as a constant. For example,

the INPUT object created by the code

Input.Marginals(1).Type = 'Gaussian';

Input.Marginals(1).Parameters = [0 1];

Input.Marginals(2).Type = 'Gaussian';

Input.Marginals(2).Parameters = [1 0];

myInput = uq_createInput(Input);

has the second marginal set to the constant 1. The following warning message is raised:

Warning: Marginal(2).Type changed from Gaussian to constant because

the variance was zero.

Similarly, a bounded random variable with identical upper and lower bound is reverted to a

constant. For example, the INPUT object created by the code

Input.Marginals(1).Type = 'Gaussian';

Input.Marginals(1).Parameters = [0 1];

Input.Marginals(2).Type = 'Gaussian';

Input.Marginals(2).Parameters = [0 1];

Input.Marginals(2).Bounds = [0 0];

myInput = uq_createInput(Input);

has the second marginal set to the constant 0. The following warning is raised:

Warning: Marginal(2).Type changed from Gaussian to constant because

the upper and lower bounds were identical.

UQLAB-V1.3-102 - 29 -

Chapter 3

Reference List

How to read the reference list

Structures play an important role throughout the UQLAB syntax. They offer a natural way

to semantically group conﬁguration options and output quantities. Due to the complexity of

the algorithms implemented, it is not uncommon to employ nested structures to ﬁne-tune

the inputs and outputs. Throughout this reference guide, a table-based description of the

conﬁguration structures is adopted.

The simplest case is given when a ﬁeld of the structure is a simple value or array of values:

Table X: Input

.Name String A description of the ﬁeld is put here

which corresponds to the following syntax:

Input.Name = 'My Input';

The columns, from left to right, correspond to the name, the data type and a brief description

of each ﬁeld. At the beginning of each row a symbol is given to inform as to whether the

corresponding ﬁeld is mandatory, optional, mutually exclusive, etc. The comprehensive list

of symbols is given in the following table:

Mandatory

 Optional

⊕ Mandatory, mutually exclusive (only one of

the ﬁelds can be set)

 Optional, mutually exclusive (one of them

can be set, if at least one of the group is set,

otherwise none is necessary)

When one of the ﬁelds of a structure is a nested structure, a link to a table that describes the

available options is provided, as in the case of the Options ﬁeld in the following example:

UQLAB user manual

Table X: Input

.Name String Description

 .Options Table Y Description of the Options

structure

Table Y: Input.Options

.Field1 String Description of Field1

 .Field2 Double Description of Field2

In some cases, an option value gives the possibility to deﬁne further options related to that

value. The general syntax would be:

Input.Option1 = 'VALUE1' ;

Input.VALUE1.Val1Opt1 = ...;

Input.VALUE1.Val1Opt2 = ...;

This is illustrated as follows:

Table X: Input

.Option1 String Short description

'VALUE1' Description of 'VALUE1'

'VALUE2' Description of 'VALUE2'

 .VALUE1 Table Y Options for 'VALUE1'

 .VALUE2 Table Z Options for 'VALUE2'

Table Y: Input.VALUE1

 .Val1Opt1 String Description

 .Val1Opt2 Double Description

Table Z: Input.VALUE2

 .Val2Opt1 String Description

 .Val2Opt2 Double Description

Note: In the sequel, double and doubles mean a real number represented in double

precision and a set of such real numbers, respectively.

UQLAB-V1.3-102 - 32 -

The Input module

3.1 Creating an INPUT object: uq_createInput

Syntax

myInput = uq_createInput(Input)

Input

The struct variable Input contains the description of the marginal distributions of the input

parameters as well as their dependence through the copula function.

The content of the Input structure is listed in Table 4. 1

Table 4: Input

.Marginals Table 5 The options regarding the marginals

of the random vector

 .Copula Table 6 The options regarding the copula (or

copulas) of the random vector

 .Name String The name of the object. If not set by

the user, a unique string is

automatically assigned to it, e.g.

'Input 1'.

The options that can be deﬁned under Input.Marginals are given in Table 5. 2

Table 5: Input.Marginals

.Type String Type of marginal distribution

'Constant' A constant value

'Gaussian' Gaussian distribution (Section A.2)

'Lognormal' Lognormal distribution (Section A.3)

'Uniform' Uniform distribution (Section A.1)

'Exponential' Exponential distribution

(Section A.8)

'Beta' Beta distribution (Section A.9)

'Weibull' Weibull distribution (Section A.6)

'Gumbel' Gumbel maximum extreme value

distribution (Section A.4)

'GumbelMin' Gumbel minimum extreme value

distribution (Section A.5)

'Gamma' Gamma distribution (Section A.7)

'Triangular' Triangular distribution

(Section A.10)

'Logistic' Logistic distribution (Section A.11)

UQLAB-V1.3-102 - 33 -

UQLAB user manual

'Laplace' Laplace distribution (Section A.12)

other String A user-deﬁned marginal type

(Section 2.7)

⊕ .Moments variable length Double • Mean and standard

deviation([µ, σ]) of the marginal

distribution

• In case of constants just the

constant value is needed.

• For Beta distribution [µ, σ, a, b] can

be used for deﬁning a custom

support, otherwise it is assumed that

[a, b] = [0, 1]

• For exponential distribution a

single element in .Moments is

needed (both mean and standard

deviation)

⊕ .Parameters variable length Double • The parameters of the marginal

distribution as deﬁned in Section 1.2

• In case of constants just the

constant value is needed.

• For Beta distribution either the

parameters [r, s] can be set (then the

support is assumed to be

[a, b] = [0, 1]) or all [r, s, a, b] can be

set for deﬁning a custom support

[a, b].

 .Bounds 1 × 2 Double

default: [-inf, inf]

min

, X

max

] admissible value

Note: Only one of the two ﬁelds Input.Marginals.Parameters or

Input.Marginals.Moments can be set by the user for each element of

Input.Marginals. If both ﬁelds are speciﬁed, an error is returned.

The options that can be deﬁned under Input.Copula are listed in Table 6. 3

Table 6: Input.Copula

.Type String

default:

'Independent'

Copula type.

'Independent' Independent copula.

'Gaussian' Gaussian copula

'Pair' Pair copula

'CVine' C-vine copula

'DVine' D-vine copula

UQLAB-V1.3-102 - 34 -

The Input module

 .Parameters • For 'Independent'

copula: ignored;

• For 'Gaussian'

copula: M × M Double;

• For 'Pair' copula:

variable length Double;

• For 'C'/'DVine': cell

of M(M − 1)/2 Doubles;

• The 'Independent' copula has

no parameters

• Linear correlation matrix of the

'Gaussian' copula

• Array of 'Pair' copula

parameter(s)

• Parameters of each pair copula in

the 'CVine'/'DVine'

 .RankCorr M ×M Double Spearman correlation matrix

('Gaussian' copula only)

Additional mandatory and optional options accepted when Copula.Type='Pair' (resp.

Copula.Type='CVine' or 'DVine') are listed in Table 7 (resp. Table 8).

Table 7: Input.Copula: additional fields when Input.Copula.Type='Pair'

.Family String Pair copula family

'Independent' or

'Independence'

Independence pair copula

'Gaussian' Gaussian pair copula

'Clayton' Clayton pair copula

'Gumbel' Gumbel pair copula

'Frank' Frank pair copula

't' t- pair copula

 .Rotation Double

default: 0

Either 0, 90, 180 or 270

Rotation of copula density; see

(1.13)

Table 8: Input.Copula: additional fields when Input.Copula.Type='CVine'/'DVine'

.Structure Array of M integers Vine structure. Can be any

permutation of [1, 2, . . . , M ]

.Families Cell of Strings Families of pair copulas composing

the vine. Possible values are listed in

Table 7 (see .Family)

 .Rotations Array of Doubles

default: [0, 0, . . . , 0]

Entries must takes values

0, 90, 180 or 270

Rotation of each pair copula density;

see (1.13)

 .Truncation Integer

default: M

Vine truncation level

UQLAB-V1.3-102 - 35 -

UQLAB user manual

NOTE: Instead of manually specifying the structures Input.Marginals and Input.Copula,

it is possible to obtain them through convenience functions described in Section 3.7. Beside,

the following functions may be useful to properly specify suitable copulas:

• uq_PairCopulaParameterRange(family): provided a pair copula family as a char

(e.g., 'Gumbel'), this function returns the range of admissible values for each parame-

ter of the copula;

• uq_CopulaSummary: for a copula of vine type, prints the pairs of variables coupled by

each pair copula in a speciﬁed vine, and the corresponding conditioning variables. For

more details, see Section 3.8.5.

Output

After uq_createInput completes its operation, a new INPUT object is created that contains

the following ﬁelds: 4

Table 9: myInput = uq_createInput(...)

.Name String The name of the INPUT object

.Sampling Struct Information regarding the default and lastly

used sampling method. See Sampling for

contents

.Marginals M × 1 Struct Information regarding the marginals, see

Table 5 for contents

.Copula Struct Information regarding the copula, see Table 6

for contents

.Internal Struct Internal ﬁelds that are only of interest for

scientiﬁc developers

The structure Sampling contains the following ﬁelds : 5

Table 10: myInput.Sampling

.DefaultMethod String

Table 11

The default sampling method

.Method String

Table 11

The current sampling method

UQLAB-V1.3-102 - 36 -

The Input module

3.2 Getting samples from an INPUT object: uq_getSample

Syntax

X = uq_getSample(N)

X = uq_getSample(myInput,N)

X = uq_getSample(N,method)

X = uq_getSample(myInput,N,method)

X = uq_getSample(N,method,Name,Value)

X = uq_getSample(myInput,N,method,Name,Value)

X = uq_getSample(...)

[X, U] = uq_getSample(...)

Description

X = uq_getSample(N) returns N samples of a random vector deﬁned in the currently

selected INPUT module using the default sampling method. If not set otherwise by the

user, the default sampling method is 'MC' (Monte Carlo). The user can call the function

uq_setDefaultSampling to change the default sampling method.

X = uq_getSample(myInput,N) returns N samples of the random vector deﬁned in the IN-

PUT object myInput using the default sampling method.

X = uq_getSample( myInput,N,method) returns N samples of a random vector deﬁned in

the currently selected INPUT object using the sampling method deﬁned in method. This is a

string that can take one of the following values: 6

Table 11: method option of uq_getSample

'MC' Monte Carlo

'LHS' Latin Hypercube

'Sobol' Sobol series

'Halton' Halton series

X = uq_getSample( myInput,N,method, Name, Value) allows for speciﬁcation of addi-

tional Name - Value pairs of options. The supported options are listed in Table 12.

Table 12: Available options of uq_getSample

Name Value Description

method = 'LHS'

'LHSiterations' Integer

default: 5

Maximum number of

iterations to perform in

an attempt to improve the

design. For more

information refer to the

MATLAB function

lhsdesign.

UQLAB-V1.3-102 - 37 -

UQLAB user manual

Output

X = uq_getSample(...) returns an N-by-M matrix of the samples of the selected random

vector in the physical space (where M is the dimension of the random vector).

[X, U] = uq_getSample(...) additionally returns an N-by-M matrix (U) of the samples

in the uniform space.

3.3 Printing/Visualizing an INPUT object

UQLAB offers two commands to conveniently print reports containing contextually relevant

information for a given object.

3.3.1 Printing information: uq_print

Syntax

uq_print(myInput);

Description

uq_print(myInput) prints a report about the INPUT object myInput (type, name, param-

eters and moments of each marginal and brief information about the copula).

3.3.2 Graphical visualization: uq_display

Syntax

uq_display(myInput);

uq_display(myInput, idx);

uq_display(myInput, idx, 'marginals');

Description

uq_display(myInput) produces a sample set from the INPUT object myInput. Then it

produces M × M plots in a single ﬁgure. Each plot, indexed by i, j = 1, . . . , M corre-

sponds to the scatter plot between the i-th and j-th element of the random vector. The

diagonal elements (i.e.when i = j) contain the histogram of the corresponding element

of the random vector. If M = 1 it produces plots of the PDF and CDF of the random

variable instead.

uq_display(myInput, idx) only takes into account the input indices that are contained

in the vector idx. In particular, if idx is a single integer, this command produces plots

of the PDF and CDF of that particular component.

UQLAB-V1.3-102 - 38 -

The Input module

uq_display(myInput, idx, 'marginals') only takes into account the input indices

that are contained in the vector idx and regardless of its size, it produces plots of the

PDF and CDF of each component.

Examples

uq_display(myInput, [1 3]) will display the plots only for the ﬁrst and third element of

the random vector that is described by myInput.

3.4 Enriching an existing sample set

3.4.1 Enriching a Latin Hypercube: uq_enrichLHS

Syntax

X1 = uq_enrichLHS(X0, N)

X1 = uq_enrichLHS(X0, N, myInput)

[X1, U1] = uq_enrichLHS(...)

Input

X1 = uq_enrichLHS(X0, N) enriches the experimental design X0 deﬁned in the currently

selected INPUT object with N new samples so that the enriched sample set forms a (pseudo-)

Latin Hypercube sampling.

Note: The initial sample set is expected to form a Latin Hypercube, i.e. it should be

generated using Latin Hypercube sampling! If that is not the case, the function

uq_LHSify should be used instead (see Section 3.4.4).

X1 = uq_enrichLHS(X0, N, myInput) enriches the experimental design X0 deﬁned in the

INPUT object myInput with N new samples so that the enriched sample set forms a Latin

Hypercube.

Output

X1 = uq_enrichLHS(...) returns an N-by-M matrix of the new samples of the selected

random vector in the physical space.

Note: X1 only contains the new samples in the physical space. The enriched sample set

is obtained by X = [X0;X1].

[X1, U1] = uq_enrichLHS(...) additionally returns an N-by-M matrix (U1) of the new

samples in the uniform space.

UQLAB-V1.3-102 - 39 -

UQLAB user manual

3.4.2 Enriching a Sobol sequence: uq_enrichSobol

Syntax

X1 = uq_enrichSobol(X0, N)

X1 = uq_enrichSobol(X0, N, myInput)

[X1, U1] = uq_enrichSobol(...)

Input

X1 = uq_enrichSobol(X0, N) enriches the experimental design X0 deﬁned in the cur-

rently selected INPUT object with N new samples that correspond to the next elements of

the Sobol sequence.

Note: The initial sample set is expected to be generated using Sobol sampling.

X1 = uq_enrichSobol(X0, N, myInput) enriches the experimental design X0 deﬁned in

the INPUT object myInput with N new samples that correspond to the next elements of the

Sobol sequence.

Output

X1 = uq_enrichSobol(...) returns an N-by-M matrix of the new samples of the selected

random vector in the physical space.

Note: X1 only contains the new samples in the physical space. The enriched sample set

is obtained by X = [X0;X1].

[X1, U1] = uq_enrichSobol(...) additionally returns an N-by-M matrix (U1) of the new

samples in the uniform space.

3.4.3 Enriching a Halton sequence: uq_enrichHalton

Syntax

X1 = uq_enrichHalton(X0, N)

X1 = uq_enrichHalton(X0, N, myInput)

[X1, U1] = uq_enrichHalton(...)

Input

X1 = uq_enrichHalton(X0, N) enriches the experimental design X0 deﬁned in the cur-

rently selected INPUT object with N new samples that correspond to the next elements of the

Halton sequence.

Note: The initial sample set is expected to be generated using Halton sampling.

UQLAB-V1.3-102 - 40 -

The Input module

X1 = uq_enrichHalton(X0, N, myInput) enriches the experimental design X0 deﬁned in

the INPUT object myInput with N new samples that correspond to the next elements of the

Halton sequence.

Output

X1 = uq_enrichHalton(...) returns an N-by-M matrix of the new samples of the selected

random vector in the physical space.

Note: X1 only contains the new samples in the physical space. The enriched sample set

is obtained by X = [X0;X1].

[X1, U1] = uq_enrichHalton(...) additionally returns an N-by-M matrix (U1) of the

new samples in the uniform space.

3.4.4 Pseudo-LHS enrichment: uq_LHSify

Syntax

X1 = uq_LHSify(X0, N)

X1 = uq_LHSify(X0, N, myInput)

[X1, U1] = uq_LHSify(...)

Input

X1 = uq_LHSify(X0, N) enriches the experimental design X0 deﬁned in the currently se-

lected INPUT object with N new samples so that the enriched sample set forms a pseudo-Latin

Hypercube.

X1 = uq_LHSify(X0, N, myInput) enriches the experimental design X0 deﬁned in the IN-

PUT object myInput with N new samples so that the enriched sample set forms a pseudo-Latin

Hypercube.

Output

X1 = uq_LHSify(...) returns an N-by-M matrix of the new samples of the selected ran-

dom vector in the physical space.

Note: X1 only contains the new samples in the physical space. The enriched sample set

is obtained by X = [X0;X1].

[X1, U1] = uq_LHSify(...) additionally returns an N-by-M matrix (U1) of the new sam-

ples in the uniform space.

UQLAB-V1.3-102 - 41 -

UQLAB user manual

3.5 Sub-sampling an existing sample set: uq_subsample

Syntax

X1 = uq_subsample(X0, N1, method)

X1 = uq_subsample(X0, N1, method, Name, Value)

X1 = uq_subsample(...)

[X1, idx] = uq_subsample(...)

Input

X1 = uq_subsample(X0, N1, method) reduces the sample size of the experimental design

X0 (N0-by-M matrix) from N0 to N1 samples using the approach speciﬁed in method. The

following values are possible for method:

• 'random': The subset of N1 samples out of N0 is selected randomly

• 'k-means': The subset of N1 samples out of N0 is selected by ﬁrst performing k-means

clustering with k = N1. Subsequently, the N1 samples closest to the cluster centroids

are selected.

X1 = uq_subsample(X0, N1, method, Name, Value) allows for ﬁne-tuning various pa-

rameters of the subsampling algorithm by specifying Name and Value pairs of options. The

available options are summarised in Table 13.

Table 13: Available options of uq_subsample(..., Name, Value)

Name Value Description

The following options are taken into account when method = 'kmeans'

'Distance_kmeans' String

default:

'sqeuclidean'

The distance measure

that is used in k-means

clustering. The available

options can be found in

the documentation of the

built-in MATLAB function

kmeans (option

'Distance').

'Distance_nn' String

default: 'euclidean'

The distance measure

that is used in nearest

neighbour search for

determining the samples

closest to the k-means

centroids. The available

options can be found in

the documentation of the

built-in MATLAB function

knnsearch (option

'Distance').

UQLAB-V1.3-102 - 42 -

The Input module

Output

X1 = uq_subsample(...) returns an N1-by-M matrix that contains a subset of the samples

in X0.

[X1, idx] = uq_subsample(...) additionally returns the indices of the selected samples.

3.6 Transforming samples between spaces

3.6.1 uq_GeneralIsopTransform

Syntax

Y = uq_GeneralIsopTransform(X, XMarginals, XCopula, YMarginals, ...

YCopula)

Input

The uq_GeneralIsopTransform function allows one to transform a sample set X (of size

N × M) drawn from a random vector deﬁned by XMarginals and XCopula into samples of

a random vector Y deﬁned by YMarginals and YCopula.

The guidelines for specifying the structures XMarginals, XCopula, YMarginals and

YCopula can be found in Section 3.1 (the syntax of structures Input.Marginals from Ta-

ble 5 and Input.Copula from Table 6 are used respectively).

Output

Y = uq_GeneralIsopTransform(...) returns an N-by-M matrix Y that contains the trans-

formed sample set.

3.6.2 uq_IsopTransform

Syntax

Y = uq_IsopTransform(X, XMarginals, YMarginals)

Input

The uq_IsopTransform function allows one to transform a sample set X (of size N × M)

drawn from a random vector with marginals XMarginals into samples of a random vector Y

with marginals YMarginals assuming that the components are independent. The guidelines

for specifying the structures XMarginals and YMarginals can be found in Table 5 (Sec-

tion 3.1).

UQLAB-V1.3-102 - 43 -

UQLAB user manual

Note: The .Type and .Parameters ﬁelds of X_marginals, Y_marginals are nec-

essary. In case the moments are given for some marginals the function

uq_MarginalFields can be executed ﬁrst in order to obtain the corresponding

parameter values.

Output

Y = uq_IsopTransform(...) returns an N -by-M matrix Y that contains the transformed

sample set.

3.6.3 uq_NatafTransform

Syntax

U = uq_NatafTransform( X, XMarginals, XCopula)

Input

The uq_NatafTransform function allows one to transform a sample set X (of size N × M )

into the standard normal space (space of zero mean, unit variance independent normal vari-

ables). The space is deﬁned by the structures XMarginals and XCopula. The guidelines

for specifying XMarginals (resp. XCopula) can be found in Table 5 (resp. Table 6) in Sec-

tion 3.1.

Output

U = uq_NatafTransform(...) returns an N-by-M matrix U that contains N samples from

M independent standard normal variables resulting from the Nataf transform of X.

3.6.4 uq_invNatafTransform

Syntax

X = uq_invNatafTransform( U, XMarginals, XCopula)

Input

The uq_invNatafTransform function allows one to transform a sample set U (of size N ×M )

drawn from a standard normal random vector into samples of a random vector X deﬁned by

XMarginals and XCopula. The guidelines for specifying XMarginals (resp. XCopula) can

be found in Table 5 (resp. Table 6) in Section 3.1.

UQLAB-V1.3-102 - 44 -

The Input module

Output

X = uq_invNatafTransform( ... ) returns an N-by-M matrix X that contains N samples

of size M, each row being a realization of the random vector deﬁned by XMarginals and

XCopula.

3.6.5 uq_RosenblattTransform

Syntax

U = uq_RosenblattTransform( X, XMarginals, XCopula)

Input

The uq_RosenblattTransform function allows one to transform a sample set X (of size

N × M) into the standard uniform space (space independent variables with uniform distri-

bution in [0, 1]). The original space is deﬁned by the structures XMarginals and XCopula.

The guidelines for specifying XMarginals (resp. XCopula) can be found in Table 5 (resp.

Table 6) in Section 3.1.

Output

U = uq_RosenblattTransform(...) returns an N-by-M matrix U that contains N samples

from M independent standard normal variables resulting from the Nataf transform of X.

3.6.6 uq_invRosenblattTransform

Syntax

X = uq_invRosenblattTransform( U, XMarginals, XCopula)

Input

The uq_invRosenblattTransform function allows one to transform a sample set U (of size

N × M) drawn from a standard uniform random vector into samples of a random vector

X deﬁned by XMarginals and XCopula. The guidelines for specifying XMarginals (resp.

XCopula) can be found in Table 5 (resp. Table 6) in Section 3.1.

Output

X = uq_invRosenblattTransform( ... ) returns an N-by-M matrix X that contains N

samples of size M, each row being a realization of the random vector deﬁned by XMarginals

UQLAB-V1.3-102 - 45 -

UQLAB user manual

and XCopula.

3.7 Convenience functions to deﬁne marginals and copulas

3.7.1 uq_Marginals

The uq_Marginals function generates a structure describing M marginal distributions all of

the speciﬁed type and parameters (or moments). uq_Marginals allows one to quickly deﬁne

a multivariate INPUT with identical marginals, as in the following examples:

% G e n e r a t e an I n p u t o b j e c t wi t h 3 Gumbel m a r g i n a l s o f p a r a m e t e r s

% 1 and 2 , and i n de p e n de n c e c o p u l a

iOpts.Marginals = uq_Marginals(3, 'Gumbel', [1, 2]);

myInput = uq_createInput(iOpts);

% G e n e r a t e a t r i v a r i a t e i n p u t w i t h Gumbel m a r g i n a l s o f moments

% 2 and 2 , and i n de p e n de n c e c o p u l a

iOpts.Marginals = uq_Marginals(3, 'Gumbel', {}, [2, 2]);

myInput = uq_createInput(iOpts);

Syntax

myMarginals = uq_Marginals(Dimension, Type, Parameters, Moments)

Input

Dimension: integer describing the number of standard normal marginal.

Type : char, name of distribution family (common to each marginal)

Parameters / Moments: array, distribution parameters / moments. Only one can be speci-

ﬁed, not both. Set the other to {}.

Output

Structure myMarginals with elements myMarginals(i), i = 1, . . . , M, each having the fol-

lowing ﬁelds

myMarginals(i).Type = 'Gaussian'

myMarginals(i).Parameters = [0,1]

3.7.2 uq_StdNormalMarginals

The uq_StdNormalMarginals function generates a structure describing M standard normal

marginal distributions. It is a special case of uq_Marginals with Type='Gaussian' and

Parameters=[0 1]. uq_StdNormalMarginals allows one to quickly deﬁne a multivariate

standard normal INPUT by the following code:

UQLAB-V1.3-102 - 46 -

The Input module

iOpts.Marginals = uq_StdNormalMarginals(M);

myInput = uq_createInput(iOpts);

Syntax

myMarginals = uq_StdNormalMarginals(M)

Input

M: integer describing the number of standard normal marginal.

Output

Structure myMarginals with elements myMarginals(i), i = 1, . . . , M, each having the fol-

lowing ﬁelds

myMarginals(i).Type = 'Gaussian'

myMarginals(i).Parameters = [0,1]

3.7.3 uq_StdUniformMarginals

The uq_StdUniformMarginals function generates a structure describing M standard uni-

form distributions, that is, uniform distributions in the interval [0, 1]. The syntax is the same

as for uq_StdNormalMarginals (see above). The generated marginals, however, are of the

type 'Uniform'.

3.7.4 uq_KernelMarginals

Syntax

myInput = uq_KernelMarginals(X, bounds, bandwidth)

Creates a structure that describes the marginal distributions of the data points in X as kernel

density estimates.

Input

X : matrix of input data.

Each column X_i=X(:,ii) represents data from input variable X

, i = 1, . . . , M.

bounds: positive ﬂoat or M ×2 Double, optional.

UQLAB-V1.3-102 - 47 -

UQLAB user manual

If speciﬁed, the marginals are bounded. Can be:

• a positive ﬂoat: deﬁned dX

= max(X

)−min(X

), each j-th marginal is bounded

in [min(X

) − bounds ∗dX

, max(Xj) + bounds ∗ dX

]

• an M ×2 Double: marginal jj is bounded in bounds(jj,:)

• an cell of M elements: marginal jj is bounded in bounds

bandwidth: ﬂoat, cell, or array, optional.

The Gaussian kernel bandwidth. Can be:

• a positive ﬂoat: the kernel bandwidth for each dimension

• an array/cell of M positive ﬂoats: the bandwiths of each dimension

Output

Marginals: structure

Structure that contains M marginals obtained by kernel smoothing.

3.7.5 uq_GaussianCopula

Usage

Copula = uq_GaussianCopula(C, corrType)

Convenience function to create a data structure describing a Gaussian copula with spec-

iﬁed correlation matrix.

Input

C: M ×M double

correlation matrix of the M-variate Gaussian copula

corrType : char, optional

the type of correlation provided in C. Either 'Linear' (equivalently 'Pearson'),

'Spearman', or 'Kendall'.

Default: 'Linear'

Output

Copula: struct

Structure that contains the speciﬁed Gaussian copula, with the ﬁelds .Type,

.Dimension, .Parameters, .RankCorr, .RhoS, .TauK, .CholR

3.7.6 uq_PairCopula

Usage

Copula = uq_PairCopula(family, theta, rotation)

Convenience function to create a data structure describing the speciﬁed pair copula.

The structure is used in copula-related operations in UQLAB, for instance as part of an

INPUTobject.

UQLAB-V1.3-102 - 48 -

The Input module

Input

family: char

the pair copula family

theta : array of doubles

the copula parameters

rotation: double, optional

the rotation of the copula density. Can be: 0, 90, 180, 270.

Default: 0 (no rotation).

Note: rotations 90 and 270 are obtained by ﬂipping the copula density around the lines

= 0.5 and u

= 0.5, respectively.

Output

Copula: struct

Structure that contains the speciﬁed pair copula, with the ﬁelds .Type, .Family,

.Dimension, .Parameters, .Rotation

3.7.7 uq_VineCopula

Usage

Copula = uq_VineCopula(type, structure, families, thetas, rotations, truncation)

Convenience function to create a data structure describing the speciﬁed vine copula.

Input

type: char

either 'CVine' or 'DVine'

structure : array of M integers

array with all and only integers 1 to M, in any order.

families: cell of M(M − 1)/2 chars

the families of pair copulas comprising the vine

thetas: cell of M(M − 1)/2 arrays

each j-th element in the cell is the (list of) parameter(s) of the j-th pair copula

rotations: 1 × M(M −1)/2 Double, optional

the rotation of each pair copula density (0, 90, 180, or 270)

Default: 0 (no rotation)

truncation: Integer, optional

UQLAB-V1.3-102 - 49 -

UQLAB user manual

the vine truncation. Pair copulas in the vine with higher conditioning order that the vine

truncation are set to be the independence pair copula.

Default: M −1 (no truncation)

Note: Vine copulas truncated at tree t < M − 1 need the speciﬁcation of only

P =

j=1

(M − j) pair copulas. Consequently, the input parameters families,

thetas and rotations need to contain only P elements for truncated vines.

Additional ones are ignored.

Output

Copula: struct

Structure that describes the speciﬁed vine copula

3.8 Additional functions

3.8.1 uq_sampleU

Syntax

U = uq_sampleU(N, M)

U = uq_sampleU(N, M, options)

Input

U = uq_sampleU(N, M) returns N samples of a random vector having M independent, uni-

form marginals over [0, 1] (i.e. uniform sample over the unit hypercube of dimension M).

U = uq_sampleU(N, M, options) returns N samples of a random vector having M in-

dependent uniform marginals over [0, 1], with sampling options deﬁned in the structure

options (Table 14).

Table 14: options of uq_sample_u

 .Method String

default: 'MC'

Sampling method

'MC' Monte Carlo

'LHS' Latin Hypercube

'Sobol' Sobol series

'Halton' Halton series

UQLAB-V1.3-102 - 50 -

The Input module

 .LHSiterations Integer

default: 5

This option is taken into account

when .Method = 'LHS'. It refers

to the maximum number of

iterations to perform in an attempt to

improve the space-ﬁlling properties

of the sample set. For more

information refer to the MATLAB

function lhsdesign.

 .SobolGen sobolset object Sobol sequence point set

 .HaltonGen haltonset object Halton sequence point set

Note: For customizing Sobol or Halton sampling, one can set the relevant ﬁelds of

options.SobolGen or options.HaltonGen objects. For more details refer to

the MATLAB documentation of sobolset and haltonset respectively.

Output

U = uq_sampleU(...) returns an N-by-M matrix of samples of the unit hypercube.

3.8.2 uq_MarginalFields

Syntax

uq_MarginalFields(marginals)

updated_marginals = uq_MarginalFields( ... )

Input

The uq_MarginalFields function computes moments of marginals from parameters and

vice versa. More precisely uq_MarginalFields computes for each marginal contained in

marginals:

• the moments marginals.Moments if the parameters marginals.Parameters are

available

• the parameters marginals.Parameters if the moments marginals.Moments are

available.

The input variable marginals is a structure as described in Table 5 (Section 3.1).

Output

updated_marginals = uq_MarginalFields( ... ) returns an updated structure having

both the Parameters and Moments ﬁelds ﬁlled.

UQLAB-V1.3-102 - 51 -

UQLAB user manual

3.8.3 uq_estimateMoments

Syntax

uq_estimateMoments(marginal)

uq_estimateMoments(marginal, Name, Value)

moments = uq_estimateMoments(...)

[moments, exit_flag] = uq_estimateMoments(...)

[moments, exit_flag, convergence] = uq_estimateMoments(...)

Input

The uq_estimateMoments function computes the moments (mean and standard deviation)

of a distribution numerically. By default the moments are estimated by numerical integration.

In case poor convergence of the integrator is observed the moments are re-estimated using a

sampling-based scheme. The sample-based method measures convergence by means of the

COV of the moments estimators (Saporta, 2006).

moments = uq_estimateMoments(marginal) calculates the moments of the distribution

that is described by the marginal structure as described in Table 5 (Section 3.1).

moments = uq_estimateMoments(marginal, Name, Value) allows for ﬁne-tuning vari-

ous parameters of the moments estimation algorithm by specifying Name, and Value pairs of

options. The available options are summarized in Table 15.

Table 15: Available options of uq_estimateMoments

Name Value (default) Description

'method' String ('Integral') Method for estimating the

moments. Currently

supported values are

'MC' for sample-based

and 'Integral' for

integral-based estimation.

The following options are taken into account when 'method'= 'MC'

'N0' Double (10

) Initial sample size

'Nstep' Double (10

) Number of additional

samples per iteration

'targetCOV' Double (0.01) The target Coefﬁcient of

Variation of the moments

estimates

'maxiter' Double (30) Maximum number of

iterations

'sampling' String ('Sobol') Method for generating

samples. See Table 14 for

available options.

'verbose' Logical (false) If set to true

convergence information

are printed after each

iteration otherwise

nothing is printed

UQLAB-V1.3-102 - 52 -

The Input module

Output

moments = uq_estimateMoments(marginal) returns a 2×1 vector that contains the mean

and standard deviation of the distribution.

[moments, exit_flag] = uq_estimateMoments(marginal) additionally returns a Boolean

variable exit_flag that is true if the algorithm converged to the speciﬁed target coefﬁcient

of variation or false otherwise. This extra output will only be available in case the sampling-

based method (method = 'MC') was used.

[moments, exit_flag, convergence] = uq_estimateMoments(marginal) additionally

returns a N

×3 matrix, where N

is the number of iterations. Each row contains the iteration

number and the corresponding estimate of the mean and standard deviation at that iteration.

This extra output will only be available in case the sampling-based method (method = 'MC')

was used.

3.8.4 uq_setDefaultSampling

Syntax

uq_setDefaultSampling(method)

uq_setDefaultSampling(myInput, method)

success = uq_setDefaultSampling(...)

Description

uq_setDefaultSampling(method) sets the default sampling method of the currently se-

lected INPUT object to method. The accepted values of method can be found in Table 11.

uq_setDefaultSampling(myInput, method) sets the default sampling method of the IN-

PUT object myInput to method.

3.8.5 uq_CopulaSummary

Syntax

This function has to different uses, with syntax either

uq_CopulaSummary(Copula),

uq_CopulaSummary(VineType, Structure).

It prints a summary of the speciﬁed copula structure (ﬁrst syntax) or of the pair copulas in a

vine with the speciﬁed type and structure.

Input

Copula: struct

UQLAB-V1.3-102 - 53 -

UQLAB user manual

A structure describing a copula

VineType: char

vine type (either 'CVine' or 'DVine')

Structure: array

vine structure (order of the variables in the vine construction)

Output

None. The function prints a message on screen.

UQLAB-V1.3-102 - 54 -

Chapter 4

Appendices

A List of univariate distributions supported in UQLAB

In this section, a brief overview of each distribution and its properties (e.g., PDF, cumulative

distribution function, support, moments,parameters) is given for reference.

A.1 Uniform distribution

Uniform distributions are commonly used to represent variables with unknown moments and

known support. The uniform distribution is the maximum entropy distribution on any closed

support.

Notation : X ∼ U (a, b)

Parameters : a, b ∈ R ; a < b

Support : D

= [a, b]

PDF : f

(x) =

[a,b]

(x)

b − a



b−a

if x ∈ [a, b]

0 if x /∈ [a, b]

CDF : F

(x) =

x − a

b − a

[a,b]

(x) =







0 if x ≤ a

x−a

b−a

if x ∈ [a, b]

1 if x ≥ b

Moments : µ

a + b

b − a

√

A particularly important uniform distribution in the ﬁeld of numerical statistics is X = U(0, 1).

In fact, every class of random number generators produces samples from this PDF (or its

multidimensional version), which are then manipulated to produce samples distributed ac-

cording any other distribution as needed. For details, see Section 1.5.

A.2 Gaussian (Normal)

Gaussian distributions are another basic family of PDF that are pervasive throughout any

ﬁelds of applied science. They are commonly employed to represent measurement error,

UQLAB user manual

-2 -1 0 1 2

0.2

0.4

0.6

0.8

1.2

-2 -1 0 1 2

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 13: PDF and CDF of uniform distributions for various parameter values.

noise terms, etc.

Notation : X ∼ N (µ, σ)

Parameters : µ ∈ R , σ > 0

Support : D

= R

PDF : f

(x) =

√

2π

−

(x−µ)

2σ

CDF : F

(x) =



1 + erf



x − µ

√



= Φ



x − µ



Moments : µ

= µ

= σ

where µ is the mean, σ

the variance and erf(·) is the error function, deﬁned by:

erf(x) =

√

−t

dt (1)

An important distribution belonging to the normal family is the so-called standard normal

distribution N(0, 1), characterized by µ = 0, σ = 1. The notation Φ(x) is used to identify the

standard normal CDF:

Φ(x) =

−∞

−t

√

2π

dt (2)

All normal distributions can be represented as linear transforms of standard normal distribu-

UQLAB-V1.3-102 - 56 -

The Input module

-1 0 1 2 3 4

0.2

0.4

0.6

0.8

1.2

1.4

1.6

1.8

-1 0 1 2 3 4

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 14: PDF and CDF of Gaussian distributions for various parameter values.

tions as follows:

N(µ, σ) = µ + σN(0, 1) (3)

A.3 Lognormal distribution

A lognormal variable is a random variable X ∼ LN (λ, ζ) such that its logarithm is a Gaussian

variable:

X ∼ LN (λ, ζ) ⇔ ln(X) ∼ N (λ, ζ) (4)

Notation : X ∼ LN (λ, ζ)

Parameters : λ ∈ R , ζ > 0

Support : D

= (0, +∞)

PDF : f

(x) =

√

2πζx

exp

−

(ln x − λ)

2ζ

CDF : F

(x) =

erf



ln x − λ

√

2ζ



= Φ



ln x − λ



Moments : µ

= e

λ+ζ

= e

λ+ζ

− 1

where λ and ζ are the mean and standard deviation of the natural logarithm of the variable

and the error function is deﬁned in Eq. (1).

Lognormal distributions are commonly used in engineering to describe parameters which are

positive in nature, such as material or physical properties. An important property of lognor-

UQLAB-V1.3-102 - 57 -

UQLAB user manual

0 1 2 3 4

0.5

1.5

2.5

3.5

4.5

0 1 2 3 4

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 15: PDF and CDF of lognormal distributions for various parameter values.

mally distributed variables is that their products and ratios are also lognormally distributed.

A.4 Gumbel distribution

The Gumbel distribution is also referred to as Extreme Value distribution of type I (EV I). Note

that in the literature the name ’Gumbel distribution’ is used to refer to either the maximum

or the minimum extreme value distribution. In UQLAB “Gumbel” refers to the maximum

Gumbel distribution .

Notation : X ∼ G (µ, β)

Support : D

= R

Parameters : µ ∈ R , β > 0

PDF : f

(x) =

−

x−µ

−e

−

x−µ

CDF : F

(x) = e

−e

−

x−µ

Moments : µ

= µ + βγ

where γ

= 0.577216 . . . is the Euler constant

πβ

√

Note that parameter µ coincides with the mode of the distribution.

The Gumbel distribution is used for modelling random variables obtained as the maximum of

identically distributed variables. It is used for instance in hydrology to model ﬂood intensity.

UQLAB-V1.3-102 - 58 -

The Input module

-1 0 1 2 3 4 5

0.5

1.5

-1 0 1 2 3 4 5

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 16: PDF and CDF of Gumbel maximum extreme value distributions for various pa-

rameter values.

A.5 Gumbel-min distribution

The Gumbel-min is also referred to as the Smallest Extreme Value (SEV) distribution or the

Smallest Extreme Value (Type I) distribution.

Notation : X ∼ G (µ, β)

Parameters : µ ∈ R , β > 0

Support : D

= R

PDF : f

(x) =

x−µ

−

x−µ

CDF : F

(x) = 1 − e

−e

−

x−µ

Moments : µ

= µ − βγ

where γ

= 0.577216 . . . is the Euler constant

πβ

√

Note that parameter µ coincides with the mode of the distribution.

The Gumbel-min distribution’s PDF is skewed to the left, unlike the Gumbel-max which is

skewed to the right (see Figures 16 and 17).

UQLAB-V1.3-102 - 59 -

UQLAB user manual

-1 0 1 2 3 4 5

0.5

1.5

-1 0 1 2 3 4 5

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 17: PDF and CDF of Gumbel-min extreme value distributions for various parameter

values.

A.6 Weibull distribution

The Weibull distribution is the last type of extreme-value distributions. It is commonly em-

ployed to parametrize time-to-failure-type variables.

Notation : X ∼ W (α, β)

Parameters : α > 0 , β > 0

Support : D

= [0, +∞)

PDF : : f

(x) =

(





β−1

−(x/α)

if x ≥ 0

0 , x < 0

CDF : : F

(x) =

(

1 − e

−(x/α)

if x ≥ 0

0 if x < 0

Moments : µ

= α Γ (1 + 1/β)

= α

Γ (1 + 2/β) −Γ (1 + 1/β)

Other uses of the Weibull distribution include the parametrization of strength or strength-

related lifetime parameters, material strength and lifetime parameters for brittle materials

(for which the weakest-link-theory is applicable).

UQLAB-V1.3-102 - 60 -

The Input module

0 1 2 3 4

0.5

1.5

2.5

0 1 2 3 4

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 18: PDF and CDF of Weibull distributions for various parameter values.

A.7 Gamma distribution

The Gamma distribution may be used to model variables which are positive in nature, such as

those connected to Poisson processes. Assuming events occur randomly in time in a Poisson

process at a constant rate λ, the time to ﬁrst occurrence follows an exponential distribution

Γ(λ, 1). The time to k-th occurrence follows a Gamma distribution Γ(λ, k).

Notation : X ∼ Γ (λ, k)

Parameters : λ > 0 , k > 0

Support : D

= [0, +∞)

PDF : f

(x) =

Γ(k)

k−1

−λx

CDF : F

(x) =

γ (k, λx)

Γ(k)

Moments : µ

√

where Γ(x) is the Gamma function deﬁned by

Γ(x) =

∞

x−1

−t

dt (5)

UQLAB-V1.3-102 - 61 -

UQLAB user manual

and γ(x, y) is the incomplete Gamma function deﬁned by

γ(k, x) =

k−1

−t

dt (6)

0 2 4 6 8

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

0 2 4 6 8

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 19: PDF and CDF of Gamma distributions for various parameter values.

A special case of Gamma distribution is X ∼ Γ(λ, 1), which corresponds to the exponential

distribution (see Section A.8).

A.8 Exponential distribution

A special case of the Gamma distribution, the exponential distribution is commonly used to

represent the time to ﬁrst-occurrence of Poissonian-type processes, e.g. radioactive decays.

Notation : X ∼ E (λ)

Parameters : λ > 0

Support : D

= [0, +∞)

P DF : f

(x) = λe

−λx

CDF : F

(x) = 1 − e

−λx

Moments : µ

= 1/λ

where λ > 0 is the scale parameter.

The Exponential distribution is also used to model the waiting times in queuing problems

(e.g., for load balancing applications in large computational facilities).

UQLAB-V1.3-102 - 62 -

The Input module

0 2 4 6 8

0.05

0.1

0.15

0.2

0.25

0.3

0.35

0.4

0.45

0 2 4 6 8

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 20: PDF and CDF of exponential distributions for various parameter values.

A.9 Beta distribution

The Beta distribution commonly used to model bounded variables.

Notation : X ∼ B(r, s, a, b)

Parameters : r > 0 , s > 0

Support : D

= [a, b]

PDF : : f

(x) =

(

(x−a)

r−1

(b−x)

s−1

(b−a)

r+s−1

B (r, s)

if x ∈ [a, b]

0 if x /∈ [a, b]

CDF : : F

(x) =











0 if x ≤ a

(b−a)

r+s−1

B(r, s)

(t − a)

r−1

(b − t)

s−1

dt if x ∈ [a, b]

1 if x ≥ b

Moments : µ

= a + (b −a)r/(r + s)

b − a

r + s

r s

r + s + 1

where B (r, s) is the Beta function:

B(r, s) =

r−1

(1 − t)

s−1

dt =

Γ(r)Γ(s)

Γ(r + s)

(7)

The support of the distribution is given by the parameters [a, b]. The shape of the distribution

is related to parameters [r, s] and their ratio:

• When r = s the PDF is symmetrical;

• If r, s > 1 the PDF is unimodal;

UQLAB-V1.3-102 - 63 -

UQLAB user manual

0 0.2 0.4 0.6 0.8 1

0.5

1.5

2.5

3.5

0 0.2 0.4 0.6 0.8 1

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 21: PDF and CDF of Beta distributions for various parameter values (D

= [0, 1]).

• if r, s < 1 the PDF is maximum at the boundaries.

A.10 Triangular distribution

Notation : X ∼ Tr(a, b, c)

Parameters : a ∈ R , a < b , a < c < b

Support : D

= [a, b]

PDF : f

(x) =











0 if x ≤ a

2(x−a)

(b−a)(c−a)

if x ∈ (a, c)

b−a

if x = c

2(b−x)

(b−a)(c−a)

if x ∈ (c, b)

0 if x ≥ b

CDF : F

(x) =











0 if x ≤ a

(x−a)

(b−a)(c−a)

if x ∈ (a, c]

1 −

(b−x)

(b−a)(b−c)

if x ∈ (c, b)

1 if x ≥ b

Moments : µ

a + b + c

√

+ b

+ c

− ab − ac − bc

√

The triangular distribution is typically used as a subjective description of a population for

which there is only limited sample data. It is based on knowledge of the minimum a and

maximum b and an “inspired guess” c of the modal value.

UQLAB-V1.3-102 - 64 -

The Input module

0 2 4 6

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

0 2 4 6

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 22: PDF and CDF of triangular distributions for various parameter values.

A.11 Logistic distribution

The logistic distribution resembles the normal distribution in shape but has heavier tails

(higher kurtosis).

Notation : X ∼ P (µ, s)

Parameters : µ ∈ R , s > 0

Support : D

= R

PDF : f

(x) =

−

x−µ

s(1 + e

−

x−µ

)

CDF : F

(x) =

1 + e

−

x−µ

Moments : µ

= µ

sπ

√

UQLAB-V1.3-102 - 65 -

UQLAB user manual

-10 0 10 20

0.05

0.1

0.15

0.2

0.25

0.3

-10 0 10 20

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 23: PDF and CDF of logistic distributions for various parameter values.

A.12 Laplace distribution

Laplace distribution is also known as double exponential distribution, because it can be

thought of as two exponential distributions (with an additional location parameter) spliced

together back-to-back.

Notation : X ∼ L(µ, b)

Parameters : µ ∈ R , b > 0

Support : D

= R

PDF : f

(x) =

exp



−

|x − µ|



CDF : F

(x) =







exp



x−µ



if x < µ

1 −

exp



−

x−µ



if x ≥ µ

Moments : µ

= µ

= b

√

UQLAB-V1.3-102 - 66 -

The Input module

-20 -10 0 10 20

0.05

0.1

0.15

0.2

0.25

0.3

0.35

0.4

0.45

0.5

-20 -10 0 10 20

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0.8

0.9

Figure 24: PDF and CDF of Laplace distributions for various parameter values.

UQLAB-V1.3-102 - 67 -

References

Aas, K., C. Czado, A. Frigessi, and H. Bakkend (2009). Pair-copula constructions of multiple

dependence. Insurance: Mathematics and Economics 44(2), 182–198. 6, 12

Bedford, T. and R. M. Cooke (2002). Vines – a new graphical model for dependent random

variables. The Annals of Statistics 30(4), 1031–1068. 6, 8

Joe, H. (1996). Families of m-variate distributions with given margins and m(m − 1)/2

bivariate dependence parameters. In L. R

uschendorf, B. Schweizer, and M. D. Taylor (Eds.),

Distributions with ﬁxed marginals and related topics, Volume 28 of Lecture Notes–Monograph

Series, pp. 120–141. Institute of Mathematical Statistics. 8

Joe, H. (2015). Dependence modeling with copulas. CRC Press. 3

Lebrun, R. and A. Dutfoy (2009). A generalization of the Nataf transformation to distribu-

tions with elliptical copula. Probabilistic Engineering Mechanics 24(2), 172–178. 10

McKay, M. D., R. J. Beckman, and W. J. Conover (1979). A comparison of three methods

for selecting values of input variables in the analysis of output from a computer code.

Technometrics 2, 239–245. 23

Nelsen, R. B. (2006). An Introduction to Copulas. Secaucus, NJ, USA: Springer-Verlag New

York, Inc. 1, 3, 5

Rosenblatt, M. (1952). Remarks on a multivariate transformation. The Annals of Mathemati-

cal Statistics 23, 470–472. 12

Saporta, G. (2006). Probabilit

es, analyse des donn

ees et statistique. Editions Technip. 52

Torre, E., S. Marelli, P. Embrechts, and B. Sudret (2019). A general framework for data-

driven uncertainty quantiﬁcation under complex input dependencies using vine copulas.

Probabilistic Engineering Mechanics 55, 1–16. 7